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0 Introduction 


The C language has always been a compiled language. This means 
that the programmer has to type in his or her program and then 
compile it to change the program into machine code. 

Unfortunately this process normally takes several minutes and only 
then can you execute your program. 

HiSoft C takes a different approach. 

It is a C Interpreter. This means you type in your program and 
execute it immediately as with a BASIC interpreter. There’s no 
waiting around for compilers and linkers. 

To do this, HiSoft C has a powerful GEM-based editor which lets you 
edit up to eight files at once. You can even create modular programs 
and then, with a simple click of the mouse, run these modules 
together. 

This gives you an easy-to-use environment where you can spot 
errors much more quickly than with a compiler. You can even single 
step and put breakpoints in your code. 

HiSoft C gives the C language the accessibility of BASIC without 
losing the language’s power. So HiSoft C is aimed at two categories of 
programmers: 

• Beginners will find HiSoft C gives them a very easy way to learn 
the C language. 

C is the language around which the Atari ST is based and is the 
language of choice for many professional programmers. Many 
newcomers to the ST decide that they would like to try out this 
powerful language. So they buy a compiler, but it seems to take 
forever to get their first program to run because of numerous 
compiler or linker errors. 

This interpreter lets beginners discover the C language more 
gently, using an environment that reminds them (or you!) of 
BASIC. 

• Experienced programmers will find HiSoft C provides a faster 
way to develop their programs. 
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Compiled and assembly language functions can be loaded and 
used with interpreted modules. HiSoft C also supports almost 
the full C language as described in Kemighan & Ritchie “The C 
Programming Language” (First Edition). 

Developers can use HiSoft C to develop their programs with all 
the advantages this gives and then, when their application is 
finished, just compile to a finished product. 

Porting programs written with the interpreter is easy as long as you 
respect the standard rules of programming. Nevertheless, each 
implementation of C (whether a compiler or interpreter) has its own 
peculiarities and extensions; so some work may be needed. This is 
the case when moving code between a compiler and the interpreter 
and between two compilers. 

HiSoft C has a library of 460 functions. These are detailed in Section 
4 and include the usual ANSI, UNIX, C, GEM and DOS standard 
functions. In addition, HiSoft C has a toolbox of functions which are 
both simple and powerful, to make programming with menus, dialog 
boxes and windows much easier. 

So, thanks to HiSoft C, you can easily write programs that use all the 
facilities of your machine, with or without GEM. Finally, if you need 
faster running code you can use your favourite compiler (Lattice C 
from HiSoft, we hope!) to speed up your programs. 


0.1 Always make a back-up 


Before using HiSoft C you should make a back-up copy of both the 
distribution disks and put the original away in a safe place. They are 
not copy-protected to allow easy back-up and to avoid inconvenience. 
The disks may be backed-up using the Desktop or any back-up 
utility. The disks are single-sided but may be used in double-sided 
drives. 

If you have a double-sided disk drive you can copy the contents of 
both disks on to one double-sided disk. If you have a hard disk, just 
drag the files to a folder on your hard disk. 

Before hiding away your master disks make a note in the box below 
of the serial number written on them. You will need to quote this if 
you require technical support. 


Serial No: 
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0.2 Registration Card 

Enclosed with this manual is a registration card which you should 
fill in and return to us after reading the licence statement. Without it 
you will not be entitled to technical support or upgrades. Be sure to 
fill in all the details, especially the serial number and version number. 
The version number is given in the About box when you run HiSoft C. 


0.3 HiSoft 

C Disk Contents 

o 

The HiSoft C disk 1 contains the following files: 

o 

HC . PRG 

FI . IC - FI 1 . IC 

the interpreter itself 

supplementary files the interpreter needs 

A 

README.TXT 

see below for details 


The HiSoft C disk 2 contains the following folders: 

o 

HEADER 

the standard C header files 

A 

HELP 

the information files used by the editor help 
command 


EXAMPLES 

example C programs 

c 

SOURCE 

the source code to the HiSoft C toolbox. See 

Appendix D.l 


DUMPFILE . * 

the files for the resource file of the DUMPFILE. C 
example 

"N 

RESOURCE . * 

the files for the rsource file of the RESOURCE. C 
example 


CHECKST . PRG 

a program to give details of your machine. Please 
include this information when writing to us. 

"H 

L. 



c 






u 
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0.4 The README File 


As with all HiSoft products HiSoft C is continually being improved 
and the latest details that cannot be included in this manual may be 
found in the readme . txt file on the disk. This file should be read at 
this point, by double-clicking on its icon from the Desktop and then 
clicking on the Show button. You can print it by clicking on the Print 
button. 


0.5 Using this manual 


Different sections of this manual are aimed at different readers. 

After this introduction, Section 1 describes how to use the Editor 
and Interpreter and so everyone should read this. 

Section 2 is an introduction to the C language for those of you who 
are new to the language. 

Section 3 is an introduction for those new to programming in GEM, 
whether experienced or novice C programmers. This section also 
provides a description of the HiSoft C GEM toolbox for experienced 
GEM programmers. 

Section 4 describes the 460 functions of the HiSoft C library. This is 
mainly designed for reference and includes a summary so you can 
find which function you need for a particular job. 

Appendix A contains the answers to the Exercises set in the tutorial 
in Section 2. You will need to use this as you work through Section 2. 

Appendix B is the reference language for the C interpreter and is 
aimed at the experienced programmer. 

Appendix C covers the interpreter’s error messages and is designed 
to be used as a reference if you don’t understand an error message. 

Appendix D covers porting programs to and from HiSoft C from and 
to other implementations. 

Appendix E is the Bibliography which recommends some further 
reading on the C langauge and the ST itself. 

Appendix F covers technical support and upgrades. 

Finally, there’s the index. 
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1 Using HiSoft C 


This section describes how to write, modify and run a program with 

HiSoft C. 


1.1 The Keyboard and the cursor 


1.1.1 The Editor 


As soon as you load HiSoft C a menu bar appears and a window 
covers most of the screen. HiSoft C uses GEM and the mouse to make 
your work easier. The menu lets you select the editor and execution 
options. The program that you type in will appear in the window. 

At the top left of the window you will see a flashing block cursor. This 
indicates where the characters you type will be inserted. 

The editor is a full-screen editor; that is to say you can move the 
cursor where you like within the window and immediately change 
the text as you wish. 

HiSoft C lets you work with eight files at the same time. If you cannot 
see the file that you want at a given instant you can very easily 
switch from one to another. 


1.1.2 Moving the cursor 


You can move the cursor in all four directions by pressing the cursor 
keys labelled < — > T and l to the right of the keyboard. You can also use 
Control S, Control D, Control E and Control X respectively. 

You can position the cursor by moving the mouse and clicking at the 
point to which you wish to move. 

You can also use the vertical scroll bar and the window’s arrow icons 
to change the cursor position. 

The following keys are for rapid cursor movement within the text: 


Shift <- 
Shift -> 
Control 
Control 


moves to the start of line 

moves to the end of line 

moves to the end of the previous word 

moves to the start of the next word 
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1.1.3 The special keys 


□ 


The following keys modify the text in some way: 


Delete 

deletes the character under the cursor. 

Backspace 

deletes the character to the left of the cursor. 

Return 

inserts a carriage return. If the cursor isn’t at 
the end of the line the line is split at the cursor 
position and the cursor moves to the beginning 
of the new line. 

Control 
Ret u rn 

inserts a new line without splitting the current 
one. 

Tab 

inserts a tab character at the cursor position 
thus moving the cursor to the next tab position. 

Shift Tab 

moves to the previous tab position. 

Undo 

‘Undoes’ any changes to the current line. 

Help 

displays some help information on a specified 
subject. 

Home 

moves the cursor to the start of the C block. A C 
block is a sequence of instructions surrounded 
by curly brackets -C and > . 

Shift Home 

moves the cursor to the end of the C block. 

Esc 

See Section 1.1.6. 

Alternate 1 
to 

Alternate 8 

select one of the eight possible files. 


There’s no need to remember these by heart; they can be displayed 
by selecting Cursor keys from the Help menu. 
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1.1.4 Function keys 

L 

The function keys when used with the Shift key work as ten macro 
function keys that can be modified by the user. See Section 1.7.1 . 

When the function keys are used without the Shift key they have 
the following meanings: 

c 

c 
u 

is- 

c 

c 

iw- 

L- 

The function keys item from the Help menu may also be used to 
display a summary of these keys. 

C 

C 


F 1 

Deletes to the end of the word : under the cursor. 
A word consists of a sequence of characters 
separated by blanks or the ends of lines. 

F 2 

Insert the last word which has been deleted with 
F 1 to the right of the cursor. If F 3 was used since 
F 1 then the line deleted by F 3 is used. 

F 3 or 
Cont ro L Y 

Delete the line containing the cursor. 

F 4 

Insert after the current line the last word 
deleted with F 1 or the last line deleted with F 3 . 

F 5 

Insert an empty line after the current line and 
position the cursor there. 

F 6 

Join the next line to the end of the current one 
by copying. 

F 7 

Comment out the current line. If the line was 
originally commented out the comment is 
removed. 

F 8 

Delete to the end of the current line. This may 
not be recovered with F 2 or F 4 . 

F9 or 

Control-R 

Move the cursor 23 lines (a screen full) towards 
the start of the file. 

FI 0 or 
Cont rol-C 

Move the cursor 23 lines (a screen full) towards 
the end of text. 
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1.1.5 Menu short cuts 


The major commands can be accessed from the keyboard without 
having to use the mouse to access the menus. 

In general these combinations consist of either the Alternate or 
the Control keys with a letter or digit. 

To the right of the menu entries is a single letter. If this is a capital 
(upper case) then this item may be selected with Alternate and the 
letter key. If this is in lower case then it can be selected with Control 
and the letter. 

Here is a list of the key combinations and the corresponding menu 
item. 


Alternate A 

Abandon 

Alternate B 

Bottom of file 

Alternate F 

Find 

Alternate G 

Go to line 

Alternate I 

Insert file 

Alternate J 

Load project 

Alternate L 

Load file 

Alternate M 

Module list 

Alternate N 

Repeat find (Next) 

Alternate 0 

Save options 

Alternate P 

Program Information 

Alternate Q 

Quit HiSoft C 

Alternate R 

Find & replace 

Alternate S 

Save as 

Shift Alternate S 

Save file 

Alternate T 

Top of file 

Alternate V 

Information on the variables 

Alternate X 

Run (execute) 

Alternate Z 

Go to last position 

Control 1 

Set mark 1 

Control 2 

Set mark 2 

Control 3 

Go to mark 1 

Control 4 

Go to mark 2 

Control C 

Page down 

Control D 

Cursor right 

Control E 

Cursor up 

Control R 

Page up 

Control S 

Cursor left 

Control X 

Cursor down 

Control Y 

Delete line 
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These combinations of keys may be modified to configure the 
keyboard in the way that you want; you can thus make the editor 
~ similar to any editor that you are used to. 

See Section 1 .8.3 for details. 

1.1.6 Keyword completion 

This facility can save a lot of typing and looking up the syntax of 
functions. 




V 


You type only the beginning of the name, and the complete function 
call (including the parameters) is automatically created by the editor. 

For example if you type: 

s t r n i 

and then press the Esc key, the editor will display: 

strnicmp(str1,str2,n) 

on the screen, with the cursor one the first argument of thefunction. 
You are now in Esc mode. Look at the top right comer of thescreen. 
E s c is displayed, instead of Ins. The editor is waiting for you to type 
in the arguments of the function. After each parameter, you should 
press Return, and the cursor is positioned on the first character of 
the nextargument. 

The parameter names which are written by the editor are 
automatically replaced by the new names you type. You don't need to 
erase the old names with Backspace or Del; just type the new one 
and press Return. If you don't want tochange the name of a 
parameter, just type Return. 

You exit Esc mode when you have typed in all the parameters, or 
when you use cursor keys or select a menu item. 

Esc mode can also be used with the C language keywords, as follows: 


short cut 

statement 

f 

for 

w 

while 

s 

s w i t c h 


The list of the functions and parameters used by E s c mode is in file 
f 1 1 . i c . You can modify this as you wish. 
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1.1.7 Menu commands 


You know how to select a menu item, now we will examine the various 
menus in detail. 

On the far left are the credits! The first entiy under the Atari logo, 
which is equivalent to the Desk menu on many ST programs, is the 
credit for the author of the program. 


1 Info | 

Variables 

m 

Progran 

HP 

Menory dunp 


Stack 


Last error 



In the Info menu on the far right, the 
Program info command displays a dialog 
box which gives some statistics for the 
current program. With this you can see 
how many lines your program has, the 
free memory figure, how much memory 
this program needs and where the 
cursor is in the text. The other 
commands on this menu will be 
discussed later. 


The Move menu commands are also useful: 


1 Move 1 

Hove cursor — 

— 

Top of file 

KT 

Bottom of file 

KB 

Go to line ... 

KG 

Go to last position 

BZ 

— Harks 

— 

Set nark 1 

A 1 

Set nark 2 

a 2 

Go to nark 1 

A Z 

Go to nark 2 

A 4 

Options 

— 

y Indentation 


Ruto line split 


Set tab length 


y Ruto Nrite 



Top of file moves the cursor to 
the front of your program and 
Bottom of File moves to the end 
(oh good - you guessed). 

When you click on the Go to 
line... item a dialog box appears 
and asks you to enter the line 
number that you want to move 
to. You are not allowed to move 
past the end of text. 

There are a set of commands 
that some people find incredibly 
useful and other people find a 
waste of time. As they weren’t 
difficult to program, they have 
been put in HiSoft C. 


These are the marks. You set a mark in your program at the cursor 
position and then after you have moved the cursor you can return to 
the place that you marked. There are two different marks that you 
can use. 
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The command Set mark 1 sets the first mark at the cursor position; 
to return there use the Go to mark 1 command. Naturally Set mark 2 
and Go to mark 2 perform the same operations for the second mark. 

The Go to last position command is similar to the marks. It is as if a 
mark was automatically placed at the last cursor position that the 
text was changed. When you click on this command the cursor 
moves to the last place that the text was modified. 

This is veiy useful when you are typing in a program. It lets you 
interrupt your typing, have a look at another part of the program 
and then continue typing where you were before. 

Note that the marks can be used to move between modules. If you go 
to a mark that is in a different module, the module switching is 
automatic. 


1.2 The File menu 


We will now describe most of the items 
on the File menu. 

The Quit command lets you leave HiSoft 
C after asking whether you wish to 
save any unsaved work. If you realise 
that you don’t want to quit you can 
cancel this command. 


Abandon clears the program in 
memory and leaves you with a blank 
screen. If you have modified the 
program without saving it you will be 
warned. 

Note that, with Abandon, only the 
current text is deleted. The other seven 
modules are left alone. This option, as 
well as the Load file, Insert file, Save File, 
and Save as commands, only affects 
the current module. 

The Load file command loads a file into memory, surprisingly 
enough. 


File 


Read 

Load file ML 

Insert file SI 

Write 

Save file OSS 

Save as. . . MS 

Options 

Save options MO 


7 Confirn abandon 
s! Confirn overwrite 
7 Backup file 
Text editor 
Auto load 

Module list MM 

End 

Abandon MA 

Quit HQ 
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The file selector appears and you can choose the file which you wish 
to load. If there is a file already loaded in this module that you haven’t 
saved then HiSoft C will ask for confirmation because the new 
program overwrites the old one in memory. 

The name you specify is displayed in the work window’s title bar. 
This is the name of the current file. 

Save file stores the program in memory on disk under the current 
name. If a name hasn’t been given yet (the title bar shows No name) 
then the file selector will appear for you to enter the file name and 
possibly change the directory (folder) or drive. 

Initially the file selector is set up in directory A:\EXAMPLES. This is 
so that you can load the examples off Disk 2 straightaway. If you want 
to save a file to a newly formatted disk, you will need to change the 
directory to A : \ * . *. Otherwise you will try to save your program in a 
non-existent directory. 

If, when you save a file, a file with the same name already exists, 
HiSoft C will ask you whether you wish to overwrite it. If you don’t 
want to, click on No and the save operation will be cancelled and the 
existing file will be left as it was. 

But if you do want to save the program with the same name, the old 
version of the program will survive with a .BAK extension rather than 
.C. 

Every time you save a program to disk, HiSoft C remembers the 
name of the file and the position of the cursor within the text. Thus 
the next time you load HiSoft C it can re-load the last program saved 
and re-position the cursor at the place that it was when you saved 
the program. You can then continue working where you left off. 

The Save as... command lets you save the current program under a 
different name to that of the file that was loaded. The file selector will 
appear so you can specify the new name. The program is then saved 
under that new name. 

Finally Insert File lets you merge a program from disk with the 
program in memory. 

You can insert a whole file in to the text in memory. The insertion 
takes place before the line after the current cursor position. 

When you select this option a file selector appears and you can 
specify the file to insert. You can only insert HiSoft C coded files 
rather than ASCII ones. If you need to insert an ASCII file you can 
convert it first to the HiSoft C format. See Section 1.9. 
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For the same reason files may not be inserted when in Text Mode. 

HiSoft C will let you suppress some of its dialog boxes if you wish. 

For example, you can suppress the alert box that appears when you 
quit with an unsaved program. You can also control whether a 
backup is made, and even whether HiSoft C automatically loads the 
last program saved. These commands are described in Section 1.8. 


1.3 Working with several files 


HiSoft C lets you work simultaneously with up to eight modules that 
contain eight different programs. 

However there is only ever one window open at once. The different 
programs appear one after another in the same window. 


1.3.1 Selecting a module 


A module is an area where you can load, modify, execute and save a 
program. There are eight such areas. The simplest way to select a 
module is to simultaneously press the Alternate key and the 
number you wish to select. For example, to select module 5 press 
Alt-5 . 

The module’s name and the name of the file being edited are shown in 
the window’s title bar. But if you have selected module 5 for the first 
time there won’t be any file loaded. The window title will be m od u l e 5 
: No name 

You can move to the next module by clicking on the “Full window” box 
on the top right of the current window. So, if you are editing module 3 
and you click on the full box you will select module 4. 


Using HiSoft C 


HiSoft C 


Page 13 


1.3.2 The Module List 


The option Module List on the File menu displays a dialog box 
containing a list of the modules. 


Aliinj Find Run Hove Block Helpjnfo Ins 


Module list. 

rj 

iModule 1 ! M:\KERMIT.C 

Not nodif ied| 


' IModule 2 : M:\DUHPFILE.C 

Not nodif ied| 


( IModule 3 : No nane 

Not nodif ied| 

t 

< IModule 4 ; No nane 

Not nodified 


3 IModule 5 : No nane 

Not nodi f ied| 

[ 

IModule It : No nane 

Not nodified 


' IModule 7 : No nane 

Not Modif ied| 

1 

( IModule 8 : No nane 

Not Modified| 

i | B 1 ock : Undefined 

1 

1 OK J 



For each module the name of the file being edited and the state of the 
file are shown. The state of the file is either Modified or Not 
modi tied. 

This command also lets you select a module easily. 

For example, say you wish to edit the file DUMPFILE. Thanks to this 
dialog box, you can see that this program is in module 2. Click on the 
box corresponding to this module and module 2 and its file 
DUMPFILE will appear on the screen. 

If you wish to exit this dialog box without changing modules click on 

OK. 

This dialog box also has another purpose. It tells you if a block has 
been marked in another module. If one has it enables you to transfer 
it to another module. See Section 1.6.3 for how to cut and paste 
between modules. 
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1.4 Running a program 


1.4.1 How’s it done? 


You have typed in a fine program or perhaps you have loaded an 
example. The only thing left is to run it. 

To do this, save your program, leave the editor and load the first pass 
of the compiler with a stack size of 4096 bytes. If there are no errors, 
load the second pass and specify that you want a GST output file. 

There will be errors. And then you will need to include the file stdio.h 
which is on disk 4. Load the editor again to fix this. And then you link 
with the wrong libraries so it still doesn’t work... 

No don’t worry it’s all lies. That’s how it used to be. 

To run your program click on Run program from the Run menu. 
That’s it. 

Press a key or click on the mouse when the program has finished 
and you’ll be back in the editor. 

But we recommend that all programs should be saved before running 
them. An array index that is a little too big or recursion that uses 20k 
memory can both crash the machine and you will have to re-load the 
interpreter. 

If the computer crashes instead of displaying bombs (you’ve coming 
across bombs no doubt) and returning to the Desktop, HiSoft C 
displays a description of the error and positions the cursor at the 
program statement that crashed HiSoft C. 

This considerably reduces the problems caused by program errors 
but doesn’t remove them completely; after such a crash, GEM may 
become confused. 

When you start a program running, the work window and menu bar 
disappear and are replaced with a blank screen. Then you are free to 
open your own windows and display your own menu. See Section 3 
for details of functions which let you do this. 

You can also deliberately stop a program that is running by pressing 
two of the Shift, Control or Alternate keys simultaneously. For 
example, press both Shift keys or Control and Shift together. 
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An alert box will appear and you are asked to confirm that you wish 
to halt execution. The work window and editor window will be re- 
displayed on the screen and the cursor positioned at the point where 
the program was interrupted. 

The function stop( ) can be used within programs to stop the 
program. 

Please note however that it is not possible to interrupt a program 
whilst a built-in HiSoft C routine is running. That is to say when a 
library function is executing. This is because the library functions are 
written in assembler rather than interpreted by HiSoft C and so the 
interpreter does not have control. Thus the program may only be 
interrupted after the function returns. This normally isn’t a problem 
as most functions execute very quickly, but the event function may 
run for several seconds and during that time the program can’t be 
stopped. 


1.4.2 Error Messages 


If you run a program you have written yourself the chances are that 
there are either syntax errors or semantic errors. 

If there is an error whilst running a program, HiSoft C displays an 
error number and message in an alert box. See Appendix C for a 
detailed description of the possible errors. 

As soon as you acknowledge the alert box describing your error, the 
cursor is positioned at the place where the error was found, so you 
can correct it straight away. 

Once your program is displayed you won’t be able to see the error 
message any more. To re-display it click on the Last error item on the 
Info menu if this isn’t disabled and this will display the last error 
message detected by HiSoft C. 

We will now describe the other items on the Run menu. 
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1.4.3 Trace Mode 


If you have an error in your 
program that you can’t identify, 
the Trace Mode will let you 
visualise the execution of your 
program. It’s a single step mode 
whereby for each instruction that 
is executed HiSoft C displays the 
program line that is executing on 
the screen. You can therefore 
follow the execution of your 
program. 

To single step a program, all you 
need to do is to select Trace mode 
from the menu; a tick mark will be 
displayed to show that it has been 
selected. Now, each time you 
execute a program, it will be in 
trace mode. 

To override this, click on Trace Mode again. The tick will disappear. 

Before executing each instruction, HiSoft C displays the 
corresponding program line on the top line of the screen. You must 
now press a key. Depending on which key you press the program will 
continue, with or without single step or will be terminated. 

If you press Return, Q or Control-C execution continues but not in 

Trace Mode. 

If you press another single key, execution continues in trace mode; 
the program line is deleted and the old screen re-drawn. Then the 
instruction is executed and so on. 

But if you press two of the Shift, Alternate and Control keys at 
the same time, execution is interrupted. The instruction that is 
displayed is not executed. 

This method of using trace mode is not of much use in some cases. 
For example if you are interested in the behaviour of the program 
around line 944 you want to go straight to the place that is causing 
the problem. 

For this reason, there is another way to access single step mode. Two 
functions enable and disable this mode, trac e_o n and trac e_o f f . 


Run 


Run progran KX 

Options 

Trace node 
Variable dunp 
Pointer test 
Clear screen 
Show cursor 
Pause after execution 

Envirannent 

y Link at runtine 
Connand tail 
Include files 
Systen nenory size 

Project 

Load project BJ 

Info about project 
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For example, in the following program trace mode is activated in the 
middle of the program and disabled towards the end. 

m a i n ( ) 

■C 

printfC” 911”); 
p r i n t f ( ” 9 2 4 ” ) ; 
p r i n t f ( " 9 2 8 ” ) ; 
trac e_on ( ) ; 
p r i n t f ( " 9 3 0 " ) ; 
pri n t f ( ” 944"); 
tra ce_of f ( ) ; 
p r i n t f ( ” 9 5 9 ” ) ; 

> 

After the t race_on instruction the progam is executed in single step 
mode. Then, after the trace_off, trace mode is disabled and the 
program runs normally. 

Note that you don’t have to select Trace mode with the mouse when 
using these two functions, and you can also have multiple uses in the 
same program, so you can use the trace functions where and when 
you want them. 


1.4.4 Following variables 


If you don’t already know the C language, skip these sections on 
variables and read them later. 

In conjunction with trace mode you can follow the values of one or 
more variables. You can see the value of one or more variables after 
each instruction if you wish. 

This facility must be used with Trace Mode. 

After the display and execution of the current instruction, a dialog 
box appears which lets you display the values of all the variables you 
want. Close this box when you have finished and then the next 
instruction will be executed. See Section 1 .4.6 for a description of this 
dialog box. 

To enable variable dump mode just select the Variable Dump option 
on the Run menu. As with trace mode there are two functions 
va r_ on ( ) and va r_of f ( ) which let you enter and exit this mode 
whilst a progam is running. 
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In Trace Mode, if you press V (for variable) when about to execute an 
instruction you will be placed in Variable Dump mode. Powerful, isn’t 
it? If you press M then this will activate the Memory dump (see 
Section 1.4.7) and pressing S will activate the Stack display (see 

Section 1.4.8). 


1.4.5 Pointer Tests 


You may know that assigning a bad value to a pointer may have 
catastrophic consequences. 

Fortunately, HiSoft C tests the values of pointers eveiy time you try 
to write to an address pointed to by a pointer. If the value of the 
pointer is junk then an error message (error 33) appears on the 
screen. 

These Pointer Tests are active by default. But if you use pointers a lot 
in a program that has been debugged you can suppress this option. 
You’ll gain a few tenths of seconds. To do this, click on the Pointer 
Test item of the Run menu and the tick will disappear. 

But you do this at your own risk... 

One bad pointer value can crash the computer if this option is 
suppressed. Remember that, instead of displaying bombs, HiSoft C 
displays an error message giving the problem that has happened 
and positions the cursor at the piece of program that tried to crash 
the machine. 
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1,4.6 Variable Dump 


The Info menu has five options. We already know about one of them, 
program Info. We will now cover the Variables option. 

This command allows you to display the names and values of 
variables of a given type. 



Value ; ? 


Variable duni 


short 


notfinis = 0 
event_ty = 3 
key = 4096 
hfiax = 378 


function 


struct 


If loat/dbll 


A File Find Run Move Block Help HQ3 

ml • - ! ' i - : • ^ Module 1 i f)i\EXBMPLES.\EVENTS.C i'i 


/# event variables */ 
int event-type; /# type of event*/ 


When you click on this menu entry a dialog box like that above 
appears. This is the same as as the box that appears when Variable 
dump mode is selected. The dialog box is split into two parts, the 
right hand side is a window where the names and values of variables 
are displayed. 

On the left are ten selectable buttons. One of these lets you leave the 
box and the other nine let you choose which types of variables you 
wish to display. 

A variable’s type is composed of an elemtentary type (char, short, 
int/long, float/double or struct) and a class (none, pointer, array or 
function ). For example, an ordinary integer variable is a combination 
of int/long and none. An array of floating point numbers is float/dbl 
and array. A pointer to a structure: struct and pointer. A function 
returning a character: char and function. 
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All types of variables can be split up like this. To display all the 
variables of a given type, you must select a type and a class by 
clicking on the appropriate buttons with the mouse. 

For example, to display all the pointers, select pointer and all the 
primary types (char, short, int/long, float/dbl, struct). In this way you 
will display all the pointers used by the program. 

If you click a second time on a button, this button will be de-selected. 
You can thus successively examine several types of variable. 

Finally a little trick we haven't mentioned before. The process above is 
a bit involved if all you want to do is display one variable. This is what 
the two small boxes near the top right of the dialog box are for Type 
the name of a variable in one and then click on the name you have 
just entered with the mouse and the value of the named variable is 
displayed in the second box. 

The values are displayed in a format that depends on the class of the 
variable. If it’s a simple variable (none) then the value is displayed in 
decimal. If it’s a pointer the hexadecimal address to which it points is 
displayed. For arrays, the address of the first element is shown and 
for functions the address of the start of the code. 

You may display several types of variables simultaneously. 

If there are too many variables to display them all in the window use 
the up and down buttons to scroll through them. 

HiSoft C displays after each value the type of the value in a simplified 
fashion. The base type is displayed first (int, char, double, 
short...) followed by an indication of the class; if the variable is a 
pointer a * is displayed, an array C ] is added, or for a function ( ) is 
added. For simple variables nothing is added. 

For STATIC variables, the module in which they are declared is also 
given. For example for a static variable declared in Module 1 , HiSoft C 
adds an extra m o d : 1 . 

This command can not be selected until the program has been run, 
nor can the variable dump be consulted if the program is changed. 
Finally, only global and static variables may be displayed - local 
variables are invisible. 

If memory is veiy short, HiSoft C can not retain the symbol table 
after execution and so this option is not available. 
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1 .4.7 Memory dump 


This command lets you look at part of the memory of your computer. 
You give it an address, and the memory area concerned is displayed 
on the screen. 

To do this, select Memory dump from the Info menu. A dialog box will 
appear that nearly fills the screen. An editable field marked Address 
lets you enter the hexadecimal address of the memory area that you 
wish to examine. 
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Press Return and a display of 256 bytes starting at the address you 
entered appears. You can click on the two arrows at the side of the 
display window and these move 256 bytes forwards and backwards. 
Each byte is displayed in both hexadecimal and ASCII. 

This command is most frequently used to examine the contents of 
structures and arrays having read their address using the Variable 
dump command. It can be accessed in trace mode by pressing M. 

The memory dump can also be activated and de-activated from 
within your program using the mem_on() and mem_off() functions. 
These work in the same way as the var_on() and var_off() functions 
described in Section 1.4.4. 
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1.4.8 Stack display | 

This command is similar to the previous command except that it lets 
you examine the area of memory used by the interpreter’s stack. It is 
here that the intrepreter stores your local variables in the order in 
which they were declared and in order of function calls. 

Thus this may be used to check the values of local variables. The local 
variables of the current function start 8 bytes from the top of the 
stack. This is the address of the local variable that is declared first, 
with the second variable next, etc. 

The stack display can be accessed in trace mode by pressing S. It can 
be activated and de- activated from within your program using the 
stack_on() and stack_off() functions. These work in the same way as 
the var_on() and var_off() functions described in Section 1.4.4. 


1.4.9 Link at runtime 


When executing your program HiSoft C can consider the modules in 
two ways. 

When the Link at runtime option is not selected, it considers the eight 
modules to be eight different programs which have nothing to do 
with each other. So when you run the program only the curent 
module is executed. 

On the other hand when Link at runtime is selected, HiSoft C 
considers that all the modules form one single progam. This lets you 
use the classic C programming style of using several modules. HiSoft 
C executes all the modules together and ‘links’ between them in the 
same way as a linker in a separate compilation system. 

So you can declare a function or variable in one module and use it in 
another module as if you were using a compiler and linker. 

If you have selected Link at runtime, HiSoft C effectively links the 
modules before running them. 
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1.4.10 Execution Environment 


There are three options on the Run menu that affect the execution of 
a program. 

They are selected or de-selected with the mouse. If an option is 
currently selected there is a tick in front of it. 


MX 


Run progran 

Options 

Trace node 
Variable dunp 
Pointer test 
Clear screen 
Show cursor 
Pause after execution 

Envlrannent 

y Link at runtine 
Connand tail 
Include files 
Systen nenory size 

Project 

Load project MJ 

Info about project 


Clear screen lets you view the 
execution of your program on a 
blank white screen rather than a 
GEM-type screen. 

Show cursor starts execution of 
the program in an environment 
similar to a . TOS program, with a 
white screen and a solid text 
cursor. 

Pause after execution waits for a 
key press or a mouse click when 
the program finishes execution 
before returning to the editor. 


These three options are saved and restored every time you save or 
load a program with the File menu commands. 

In effect, they are dependent on the program. The TOS environment 
suits some programs but not others. The automatic saving of these 
options lets the environment change with each program. 


1.4.11 Command tail 


The Command tail option from the Run menu lets you enter a list of 
arguments from the keyboard. These are passed to your program 
when it executes. 

This lets you simulate passing parameters to the program with the 
interpreter in a similar way to those passed to compiled .TTP 
programs. 


Page 24 


HiSoft C 


Using HiSoft C 



The parameters are separated by spaces except when enclosed in 
double quotes. For example, the following list, 

List of "three parameters" 

consists of three parameters: "List", "of" and "three 
parameters". 

You access the program parameters in the classic C way, that is to 
say, by having two parameters to the function main. 

The first (argc) is the number of arguments in the command line. 
The second (argv) is a pointer to an array of strings, which contain 
the parameters, one parameter in each string. 

The following program writes the parameters passed to it on the 
screen. 


main(argc,argv) 
i n t argc; 
char * * a r g v ; 


> 


whi LeCargc--) 

putsCargvCargc]); 


1.4.12 Include files 


The Include files option on the Run menu displays a list of the current 
resident include files in a dialog box. 

When a U i n c L u d e instruction is encountered during program 
execution the corresponding file is loaded into memory. The include 
files should be stored in a directory called \ HEADER on the disk from 
which HiSoft C was loaded, and you should enclose the file name ip 
angle brackets: < and >. If you use quote symbols (") then the 
interpreter will look in the directory: this will normally be that from 
which HiSoft C was loaded. 

The include files remain in memory between executions to avoid 
loading them repeatedly. This option displays a list of include files 
that have been loaded by previous runs of programs. 

You may have up to eight include files in memory simultaneously. 
The dialog box can therefore show eight file names. 
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It is possible to deliberately remove include files from memory by 
clicking the Erase resident files in the dialog box. These files 
are not deleted from the disk but only from memory. They will 
automatically be re-loaded if you run a program that needs them. 
The include files are automatically removed each time you load a 
program to ensure consistency. 

A Do not use the include files from a C compiler with HiSoft C. This 
will cause errors. HiSoft C has all the standard include files and only 
these should be used with HiSoft C. 


1.4.13 System Memory Size 


The system memory size is the amount of free memory that is not 
allocated to HiSoft C but is free for use by the Atari ST’s operating 
system. 

This memory is used for memoiy allocation (the m a l l o c function 
and friends), loading resource files (rsrc_load), the file selector and 
loading compiled procedures. 

By default this is fixed at 8K bytes. This is perhaps a little small for 
many purposes. 

If you wish to load a large resource file, or use the memory allocation 
functions extensively or load many compiled functions then this 8k 
will be too small. 

On the other hand, if you are using none of the facilities above you 
may be interested in reducing this space thus increasing the 
memory that HiSoft C can use. 

Increasing the system memory size has the effect of reducing the 
space reserved by the interpreter for the storing and running of your 
programs. 

So how do we modify this system memory size? 

Select the System memory size item from the Run menu. Enter the 
number of kilobytes you wish to allocate to system memory and click 
on OK. Save the HiSoft C configuration with Save Options from the 
File menu. Quit HiSoft C and re-load it. 

The system memory size is now the size you specified. It will be this 
value each time you load HiSoft C as this has been saved on the disk. 
To change to a new value please repeat the sequence described above. 


Page 26 


HiSoft C 


Using HiSoft C 


A HiSoft C uses this space itself. Always leave at least 6K bytes for 
the system; it is impossible to reduce this any further. 


1.5 Find and replace 


1.5.1 Finding 

Thanks to the Find... item of the Find menu you can search for a 
string of characters within a loaded program starting at the cursor 
position. 


When you select this option a dialog box appears on the screen and 
you can type in the string to search for, thus, 


FIND A STRING 


E 


| String !h slirtp 

$ 

' 



Direction 
Case sensitive 
Magic node 


Forward 


I yes I 


1 VES i 


iBackwardl 



I Find H 1 Cancel ~| 


The string that you type in may correspond exactly to the item that 
you are looking for. For example you could search for the end and 
the editor would search for those exact characters in the text. In this 
case you should leave Magic Mode set to NO. 

But you may have more exotic requirements containing a number of 
unknowns. For example, you might wish to find all the strings of 
characters starting with the end and finishing with z z . 

Equally you can search for every time a * is separated from a + by 
zero or more blanks. It’s not blindingly obvious that this is useful but 
there are many practical applications of this sort of thing. This is 
what the Magic Mode is for. 
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The string that you type will contain ordinary characters which 
match exactly the same character in the text, but there are also 
special characters as follows: 


7 

matches any single character 

x + 

match with a sequence of one or more of character 
x. i.e x, xx, xxx or more character x’s 

X* 

match with a sequence of zero or more of character 
x. That is nothing, x, xx, xxx etc 

7 * 

matches any sequence of characters. It could be no 
characters at all or a string of characters 

? + 

matches any string of at least one character 

\ ? 

matches a question mark 

\ + 

matches a plus sign 

\* 

matches an asterisk 


Some examples: 


String 
Entered : 

Strings Found: 

"qwerty" 

"qwerty" only 

"qw?rty" 

"qwarty", or " qwbrty", or "qwerty", or 
"qwerty", etc... 

"qwe+rty" 

"qwerty" or "qweerty" or "qweeerty" ... 

"qwe*rty" 

"qwrty" or "qwerty" or "qweerty" or 
"qweeerty" ... 

" qw?+rty" 

All strings starting with " q w " , and 
finishing with " r t y " , with any string with 
at least one character in between 

"qw?*rty" 

All strings starting with " q w " , and 
finishing with " r t y " , with any string 
including "qwerty" 

"qw\+rty" 

"qw+rty" only 

"qw\*rty" 

" q w * r t y " only 

"qw\?rty" 

" q w ? r t y " only 


The string that you are searching for must all be on one line of text. 
When the characters are found the cursor is automatically moved to 
that place. 
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The direction of search, Forward or Backward may be specified by 
clicking on the appropriate button. 

If you wish the search to distinguish between upper and lower case 
letters click on YES in the Case Sensitive field. If you want upper 
and lower case to be considered the same click on N o . If you click on 
N 0 , the string q w E R T is considered to the same as Q W E R T and qwert 
during the search. 

You have eight possible search strings at your disposal. Thus you 
can build up a little library of search strings that you commonly 
search for, choosing with the Find command which one you want 
this time. 

Click on the arrow button to select the find string you want; the 
current number is displayed. 

When you have found a string you can use the Repeat Find 
command to find further occurrences with the same conditions. 


1,5.2 Find and replace 

You can search for a sequence of characters and replace it with 
another. To do this choose the Find & replace item from the Find 
menu. 


SEARCH AND REPLACE A STRING 


0 

| 1 Find :h_slider | 

0 




0 

2 Replace :horiz_sl iderj | 

0 


Occurence | One 
Case sensitive 
Direction 
Magic node 

f Replace I 



The dialog box has two lines so you can enter two strings. The first is 
the string to search for and the second is the string that will replace 
it. You can switch between the two fields using the up and down 
cursor keys. 
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You can use all the same facilities that are available with the ordinary 
Find.., command. 

You can use wildcards, access 8 find strings, select the search 
direction and whether the search is to be case sensitive. 

There are three modes for using replace. You choose which one by 
clicking on one of three buttons. You can choose to replace one, 
several or all occurrences of a string. 

• Replace One occurrence 

This replaces only one occurrence. The first one found is 
replaced. 

• Replace All occurrences 

All occurrences found are replaced. This starts from the 
cursor and in the direction specified. 

During the operation of this command, if you press one of 
the Shift, Control or Alternate keys the replace operation 
continues but in "Some Occurrences" mode. See below. 

• Replace Some Occurrences 

This is the most commonly used option. For each 
occurrence the cursor is positioned where the string has 
been found. A small dialog box with three buttons is 
displayed. HiSoft C asks if you wish to replace this 
occurrence. You can: 

• Replace this occurrence and find the next one (click on Yes 
or type Return). 

• Not replace this occurrence and find the next one (click on 
No). 

• Stop searching without replacing this occurrence (click 
on Stop). 

This process continues until either all occurrences have 
been found or you stop the search. 


A 


Be careful not to do a replace operation that will leave a comment 
line or a string without its terminator. An error message will appear 
and the search will stop. 
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1.5.3 Searching in files 


The option Find string in files from the Find menu lets you search for a 
string within files on disk. A dialog box appears: 



First define the files in which the search is going to take place. To do 
this click on one of the 8 boxes for file names that you can see in the 
dialog box. You can search up to eight files at once. 


The file selector will appear; select a file and it will appear in the box 
that you clicked on. 

To remove one of the eight file names, click on the file name and then 
select Cancel in the File Selector and the name will disappear. 

To start the search click on Find. When the first occurrence is found, 
HiSoft C will display a message indicating in which file, and on what 
line within the file, the string has been found. 

You can stop the search by selecting Cancel, continue the search in 
the same file (Continue) or continue searching in the next file (Next 
file). 
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1.5.4 Find Identifier 


This option lets you find an identifier without having to type it. When 
you use this command HiSoft C will search for the next occurrence of 
the variable name under the cursor. 

Thus, if the current line is: 

printfC" %d\n",flag_ident); 

and the cursor is on the i offlag_ident then HiSoft C searches in 
the text from the cursor for the next occurrence of the identifier 
f L a g_i d e n t . 

If the identifier is not found before the end of the current file the 
search continues at the beginning. 

If there is only one reference to flag_ident in the text the cursor 
re- appears in the same place. 

You can use this command with the mouse without pulling down 
menus by first moving the mouse to the identifier that you wish to 
search for, then pressing on the right button and then clicking at the 
same time on the left button. 

This way you can search for an identifier extremely quickly. 


1.6 Block operations 


You can define a block of text and carry out various operations on it. 
For example, delete the text, copy it to another place or save it to disk. 


1.6.1 Defining a block 


A block is a collection of consecutive whole lines in the text. There are 
two ways of defining such a block, with the mouse or with the menu. 

With the mouse, double click in the first and last line of the block that 
you want to define. 
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Block 


Set top of block 
Botton of block 


Move block 
Copy block 
Save block 
Goto block start 

Hide block 
Delete block 


Inport black 


With the menu, move the cursor to the 
first line of the block and select the menu 
item Set top of block from the Block 
menu. Then move the cursor to the last 
line of the block and click on the Bottom of 
block item. 

When you have defined a block it is shown 
highlighted in inverse video (white 
characters on a black background). 

The block stays selected until you choose 
Hide block or Delete block. 


If a block is selected when you change a module the block isn’t de- 
selected but it is treated specially. See Section 1 .6.3 . 

You must select a block before using any of the commands described 
below. 


1.6.2 Block operations 


There are plenty of choices of operations to perform on blocks: 

Move block 


This command moves the block to the current cursor position. The 
block is deleted from its original position and inserted after the line 
containing the cursor. 

Note that a block may not be moved if the cursor is currently inside 
the block. 

Copy block 

This command copies the block to the cursor position. The contents 
of the block are duplicated on the line after the current cursor 
position. 

Delete block 


This command is used to remove a block of lines. 
The block is destroyed. 
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Hide block 


All this command does is de-select the current block. 

The text that was shown in reverse video is re- displayed in normal 
video; the text is not changed. 

Save Block 


The contents of the block are written to a disk file. The file selector 
appears and you can enter the name of the file to which the block will 
be written. The text in memory does not change. 

Goto block start 


This command isn't the most powerful in the editor but it can be 
useful on occasion. 


1.6.3 Copying a block to a another file 


HiSoft C lets you select a block in one module and insert its contents 
in another module. 

If you select a block and then change module the position of the block 
isn’t lost; the editor remembers which module the block is in and 
which lines it contains. 

This can be seen using the Module List command from the File menu. 

You can insert the block after the current line by selecting Import 
Block from the Block menu. 

This is the only operation you can carry out on the block when you 
are in another module, apart from re-defining it of course. 


Page 34 


HiSoft C 


Using HiSoft C 


v_- 

1.7 The Help menu 


This section describes the various commands under the Help menu. 


v_- 

Help | 


Text 



Macro connands 



Cursor keys 



Function keys 



Accessaries — 



Pocket calculator 



Ascii codes 



Print file 




Help 



Disk 



New folder 


vj 

Delete file 


Load disk util 



Disk utilities 


[ 

1.7.1 The macro commands 


You can set up ten programmable keys Shift FI to Shift F10. 
(Press a Shift key and the function key together). 


When you press one of these keys a sequence of commands is 
executed as if you had hit the equivalent keys. 
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When you select the Macro Commands menu item, a dialog box like 
that below appears: 


File Find Run Move Block BiEHJ Info 


Ins 


Module 1 ! A:\EXfiMPLES, NEVENTS.C 


Current 

nacro connands 
(Shift Fi - FIB) 


OK 


SPECIAL CHARACTERS 

Control l \ 

! Alternate 

Control P ! 

! FIB 

Control Q : 

: Fi 

Control Y ! 

: F9 

Control A : 

! 0 

Control B 

! 0 

Control C 

: o 

Control D 

: o 


print.HindoH(fun, im ) - 


printfC'Xn") 




aDaRaZ. 


/#- 


6o3o_ 


03H06030- 




-#/_ 



There are ten lines so you can enter ten sets of commands. Each line 
corresponds to one key. 

There are two sorts of characters that can be entered in the 
command strings: control characters, which are interpreted as 
commands to execute, and normal alphanumerics and punctuation. 

When the macro command is executed, normal characters simply 
appear on the screen as if they had been typed. 

Now for the control keys: 

The keys Control-P to Control-Y correspond to F 1 0 , F 1 to F 9 
respectively. For example if you select the top line of the dialog box 
(the first macro) and type Escape to clear it and then hit Control- 
S , a stylised 3 digit will appear indicating F 3 . Then pressing Shift 
FI is equivalent to pressing F3. 

if you type Control-P, Control-Q, Control-R, Control-S, 
Control-T, Control-U, in sequence the command will become 
equivalent to typing F10, FI, F2, F3, F4, F5. 
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Be careful not to confuse the non-shifted function keys and the 
shifted function keys that correspond to macro keys. The unshifted 
ones are pre-defined and can not be changed. Also the ten macro 
commands can not call each other although they may call the 
unshifted function keys as we have seen above. 

Control-Z followed by a letter is equivalent to pressing Alternate 
and the letter at the same time. This can be used to access some of 
the menu functions from macro commands. 

For example, Alternate-T selects the Top of file command. If you 
you enter Control-z and then T in a macro command this will go to 
the beginning of the file. 

Also, Control-Z followed by one of the digits 1 to 8 will select the 
corresponding module. 

The only exception to the above is that the Quit command can not be 
incorporated into a macro command. 

Cursor movements may be added to macro commands. They are 
represented by Control-A to Control-D and are echoed with 
arrows pointing in the direction of the cursor movement. 

In addition the following control codes can be entered: 

• Control-Mis equivalent to the Return key. 

• Control-H is equivalent to the Backspace key. 

Use of control characters other than those above and attempts to call 
menu items that do not exist (via a Control-z followed by a letter) 
will give an error message. 


By default the macro keys are set up as follows: 


Shift 

FI 

Add a call to the function print wi ndow to the 
file. 

Shift 

F 2 

Add a call to the function p r i n t f to the text. 

Shift 

F 3 

Duplicates the current line. 

Shift 

F 4 

Positions the cursor at the start of the file and 
calls the Find command. 

Shift 

F 5 

Adds a comment header line. 

Shift 

F 6 

Deletes the new line at the end of this line, thus 
joining the following line to it. 
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Shi ft 

F 7 

Deletes the new line at the start of this line, thus 
joining it to the previous line. 

Shift 

F 8 

Spare. 

Shift 

F 9 

Moves the cursor half a screen towards the start 
of text. 

Shift 

FI 0 

Moves the cursor half a screen towards the end of 
text. 


1.7.2 ASCII code table 


When you select the ASCII code command, HiSoft C displays a dialog 
box which shows the character codes used by the ST. 


A\ File Find Run Hove Block Hiflrt Info 


Ins 


Module 1 l No nane 



1.7.3 Print file 


The Print file option lets you print a disk file without monopolising the 
CPU. 

If Print file is selected, HiSoft C lets you enter the file to print using the 
file selector, and the file will be spooled for printing. You keep control 
of the ST and can, for example, edit or run a program while the file is 
printed - it’s magic! 
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V. 




V, 




However, despite the above, you can’t use the File menu whilst 
printing; loading and saving files is not possible, nor is leaving HiSoft 
C. If you select one of these options you will be asked whether you 
want to cancel printing so that the command you selected can then 
be executed. 


1.7.4 The Pocket Calculator 


A calculator can be used in HiSoft C by clicking on the Pocket 
calculator menu entry. It looks like this: 



In brief, it uses reverse Polish notation, is integer-only but can 
calculate in base 8, 10 and 16. 


The four standard arithmetic operations are available. To calculate 
2 0 E 3 - 1 F E 3 for example, click the digits for 20 E 3 and the larger 
up-arrow button (this is the enter key). Then enter 1 FE3 in a similar 
way. Finally press - and the answer appears. 

To change base click on the appropriate button on the right hand 
side of the calculator. The displayed value is immediately converted to 
the new base. 


You can easily see which is the current base because only the 
appropriate digits are enabled. So when you are in base 8, the digits 8, 
9, A to F are disabled and displayed in grey. In base 10, only 0 to 9 are 
enabled, and in base 16 you can use all the digits. 


The ! button clears the calculator display. 

The left arrow key deletes the last digit entered. 


The + / - changes the sign of the number. Finally to leave the 
calculator click on the close box at the top right of the display. 
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You can paste the value displayed by the calculator into your 
program by using the F 1 and F 4 keys. 


1.7.5 Help 


When you select the Help menu item, or press the Help key, a small 
dialog box appears on the screen. 

It asks you to enter the word that you would like help about. If you 
give a valid keyword, help about the appropriate word will be 
displayed. 

If the program displays an error message because it does not know 
the word that you are asking for help about, make sure that the disk 
with the HELP folder is in drive A. (Strictly this is the current drive 
when HiSoft C was loaded; so if it was loaded from drive C, the HELP 
folder will need to be on drive C). 

Obviously the help files doesn’t include every word in the Shorter 
English Dictionaiy or even Kernighan & Ritchie. So if you don’t know 
which word to type to obtain help on the subject that you are 
interested in type HIC. This will guide you to the information that 
you are looking for. 

The subjects covered by the help files are the library functions, in 
particular the HiSoft C specific ones, the menus, the error messages 
and a few others. 

You can display a list of several library functions with some 
information about each one. For each function the type returned and 
the number of parameters is displayed. To do this, enter the name of 
the function preceded by a dash or minus sign (-). For example, - 
o b j c will give all the functions starting with o b j c . This facility is 
available for all 460 library functions. 


1.7.6 The Disk Options 


You can carry out two disk operations directly from the HiSoft C 
editor. 

You can delete a file by selecting Delete file (!) from the Help menu. 
The file selector will appear and you can enter which file to delete. 

You will be asked to confirm that you wish to delete the file before it is 
destroyed. 
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You can also create a New folder. Again the file selector is used to 
enter the name of the new folder that you wish to create. 

You can also select Disk utility. This is a program that lets you copy, 
delete, and rename files and folders, format disks etc. This program 
is described in Section 1.11. 


1.8 Editor configuration 


1.8.1 Saving the configuration 


The HiSoft C editor has many parameters that can be set by the user. 

You can save the values of these options on disk so that you do not 
have to set them up eveiy time you use HiSoft C. 

The Save options command from the File menu lets you save the 
editor configuration file to disk. The options are saved in a file which 
is automatically loaded when you load HiSoft C; thus the next time 
you load the interpreter the configuration will be exactly the same as 
when you selected Save options. Of course, you must have the disk 
from which you load HiSoft C present when you use this command. 


1.8.2 Editor Options 


File 


Read 

Load file SL 

Insert file SI 

Write 

Save file <<SS 

Save as. . . BS 

Options 

Save options SO 


y Confirn abandon 
y Confirn overwrite 
y Backup file 


Text editor 


fluto load 


Module list 

SM 

End 

— 

Abandon 

SB 

Quit 

so 


There are ten menu commands that let 
you configure the editor. They selectively 
change how the editor works. 

For example, if the Confirm abandon 
item from the File menu is selected then 
you will be asked to confirm that you 
wish to abandon a file if you have 
changed it without saving it to disk. By 
default this option is selected. But if you 
wish to suppress this, click on the menu 
item. The tick mark will disappear and 
the abandon confirmation box will no 
longer appear. 


There are the following other 
configuration options on the File menu: 
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Confirm overwrite. This option informs you if you are about to save on 
top of a file that already exists. A dialog box appears asking you if you 
wish to overwrite the old file. This option is selected by default. 

Backup file. When you save a program, this option lets you keep the 
previous version by renaming this file with a . B A K extension rather 
than . C. Thus, you always have two versions of the program, the 
current one and the last one. This is another option that is selected 
by default. 

Auto load. If this option is selected, then when HiSoft C is loaded it 
automatically loads the last file that was saved and positions the 
cursor at its position when the save took place. This option is not 
selected by default. 

Text editor. This option activates a special editor mode that lets you 
use HiSoft C as a mini-word processor. See Section 1.9 for more 
details. This option is not set by default. 

The Pointer Test option from the Run menu is configurable. This 
enables testing that pointers are valid during program execution. See 
Section 1.4.5. This option is selected by default. 

The Link at runtime option is also configurable and is discussed in 
Section 1.4.9. This option is selected by default. 

Some cursor control options follow; these are on the Move menu. 


Move 1 

Hove cursor — 

— 

Top of file 

ST 

Botton of file 

SB 

Go to line ... 

SG 

Go to last position 

BZ 

Harks 

— 

Set nark 1 

M 

Set nark 2 

A 2 

Go to nark 1 

*3 

Go to nark 2 

A 4 

Options 

— 

V Indentation 


Auto line split 


Set tab length 


V Auto write 



Indentation. When this option is 
selected and you press Return the 
cursor is not necessarily 
positioned at the start of the next 
line, but under the first non- 
blank character in the line. This 
lets you enter text with a left 
margin very easily as HiSoft C will 
enter the margin for you from the 
previous line. More importantly 
however it lets you indent your 
programs in a readable manner 
without having to press the space 
bar or Tab key all the time. This 
option is selected by default. 
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v- 







V. 




Auto Wrap. When this option is selected, and you try to type a line 
that is too long to fit in the work window the editor will automatically 
enter a new line for you and you can continue to type on the next line. 
The word that you are currently typing is placed on the next line. 

When this option isn’t selected and you type a long line the screen 
scrolls sideways to let you enter lines longer than 80 characters. 
This option isn’t selected by default. 

Auto Write. When this option is selected and you type in an if or for 
statement, the interpreter will insert a matching pair of curly 
brackets, -C and > on separate lines and places you on a line between 
them: so that you can insert the code for the statements straight 
away. If you don't like this, switch just it off. 

If you do not like one or more of the options above then you can de- 
select them by clicking on the corresponding menu entry. The tick in 
front of the entry will disappear and you should then save the 
configuration using Save options from the File menu. 

Set tab length. You can change the size of tabs. By default this is five 
characters but can be set to any value you like (within reason!). When 
the editor configuration is saved the size of tabs is also saved. 

Macro commands. The current settings of the macro commands are 
saved as well so that you can set them up in exactly the way you like 
and they will always be ready when you load HiSoft C. 

And finally, the last part of the configuration is the path that is used 
for loading and saving files. The name of the disk and directory that 
you last used with the file selector is saved when you saved the 
options. 


This option is particularly useful if you have a hard disk as you don’t 
have to select the right folder every time you use HiSoft C - you are 
already there. 



1.8.3 Redefining the keyboard 

You can modify the keyboard shortcuts that are used for the menu 
commands. 


By default, Alternate Sis equivalent to selecting Save from the File 
menu; but you could change this to Control N or any other 
combination you wish. 


C 
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To do this you will need to know the keyboard scan codes 
corresponding to the key sequence that you are going to use. For 
example, for the combination Control N the code is 310E. 

To find the scan code for a given sequence, run the following program 
and type the key; the corresponding sequence will then be displayed 
on the screen. 

void mainO 

p r i n t f ( " % x \ n " , e vn t__k ey bd ( ) ) ; 
evnt_keybd( ) ; 

> 

Once you know the code put the editor in to Text Mode and load the 
file F 5 . 1 C from your backup disk 1 . 

Each line of this file corresponds to one command. The third line is 
the line for the Save file command. To change this to Control N 
replace the code for Alternate S (1F00) with that for C o n t r o l N 
(310E). 

Now save the F 5 . 1 C file, quit and reload HiSoft C. Type Control N 
and this will be equivalent to saving the file. 

Of course this should be performed with your backup copy in case 
you make a mistake. 


1.9 Editor Mode 


HiSoft C has an editor mode as opposed to the interpreter mode. The 
Editor Mode command from the File menu lets you change from one 
mode to the other. 

By default you are in interpreter mode in which HiSoft C encodes the 
lines of your program which you type although you hardly notice 
this. The program is saved on disk in this non-ASCII format; however 
this speeds up the execution of the program. 

You can remove he encoding thanks to Editor Mode. The memory 
image is always faithfully what you have typed in and is saved to disk 
in standard ASCII format. So you can use HiSoft C as a normal text 
editor. Together with the Auto Wrap command you can almost use it 
like a word processor - you can type away without ever pressing 
Return. 

But in Editor mode, you can run C programs. Clearly, you can’t have 
everything. To run programs you must be in Interpreter mode. 
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HiSoft C recognises two types of files: its own format and standard 
ASCII. You are in you can load both type of file in either mode; the 
editor will convert between them when you load. 

In Interpreter mode, you can not load C programs in ASCII that have 
been written with a compiler in mind; they will be automatically 
encoded into the internal form. Similarly you can load a program 
that you have developed with the interpreter when you are in Text 
mode and then save it out so that you can compile it or even send it to 
another machine. 


1.10 Projects and Compiled Libraries 


This section describes one of the more advanced features of HiSoft C; 
beginners are advised to ignore this for now. 


1 .10.1 What is a project? 


As far as HiSoft C is concerned a Project is a collection of files that 
make up a whole program. 

All applications can be split into one or more files. The files are of two 
types: 

C source files which are programs that are written in C and 
interpreted. A C program is composed of several modules; the 
different modules are loaded together and then interpreted as if you 
were using a linker with a compiler. 

The source files are loaded for execution into one of the eight editor 
modules. You can therefore split a C program into at most eight 
modules. 

The other type of files contain binary executable code. 

These files contain compiled functions that can be called by an 
interpreted C program. 

A project lets you link interpretable C files with machine code files 
and indicate to HiSoft C exactly which files make up the program. 

Note that a project can consist of just interpreted C modules. In this 
case loading the project loads several files in one operation. 
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1.10.2 Loading a project 


A project is described in a file with extension .PRO. When you load a 
project HiSoft C reads the file names of the C files and compiled files 
and loads them into memory in one single operation. 

For example, on the Examples disk there is the project F I ll . PRO. 
This describes a project consisting of a C file ad a function written in 
assembler. 

When you click on the Load project item on the Execute menu, the 
file selector will appear. Select the filename of the project that you 
want to load. 

The loading of C and machine code files happens automatically 
according to the description in the project file (fill. PRO for 
example). 

All you now have to do is click on Run to execute the whole project. 


1.10.3 Executable functions 


This section describes how to load machine code functions and link 
them to an interpreted program. 

You can build a function library in assembler, compiled C or another 
language and then use these procedures with an interpreted C 
program. 

These functions must always be in a special format. You can only 
have one function per file; the file name is the name of the function. 

A library file=one procedure. 

For example, if you write an assembler routine that you have called 
elephant, then you must assemble the code of the said routine to a 
file called elephant. cod. 

In practice, HiSoft C ignores what is inside the compiled file - it 
assumes that the name of the file is the name of the procedure. 

You can pass parameters to the function and it can return a value. 

You can write your procedures in assembler or C although there are 
rules for writing them because library functions that are loaded by 
HiSoft C have a different format to ordinary executable (. PRG) files. 
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1.10.4 Assembly Language functions 


If you aren’t an assembly language wizard it is probably best to skip 
to the next section. 

The entry point of your procedure is the first instruction of the 
program and you must return with an RTS instruction. 

Do not use the GEMDOS PTERM to finish the program. 

You don’t have to set up using the program’s base page as HiSoft C 
V has already done so. Trying to do this again will cause unexpected 
results. 

The following is a complete example of a function written in 
assembler. HiSoft C passes two parameters on the stack and the 
function returns the value 1 . 


This example is purely to show how this is done and is not at all 
useful. . . 


As we have seen, the entry point of the routine is the first instruction 
in the program and it terminates with a RTS. There is no base page 
manipulation. 


The two parameters that are passed are two pointers to strings of 
characters. In the C program this function is called as follows: 
writ(strl,str2). 

Ju The Link instruction makes it easier to access the parameters 
passed by HiSoft C. 8(a6) is the address of the first parameter, 
1 2 ( a 6 ) that of the second. If you have more than two parameters 
the third will be at 1 6 ( a 6 ) etc. 




All parameters are passed as 4 bytes (a long word) whether they are 
characters, integers or pointers except for floats and doubles which 
take 8 bytes. 


Function number 9 of trap 1 displays a string of characters on the 
screen. 

Link a 6 , # 0 ; I n i t i a L i s e A 6 for the parameters. 

move.L 8(a6),-(sp) ;write the first string 
move . w # 9 ( sp ) 
trap # 1 

move. I 1 2 ( a6 ) ,-( sp ) ;write the second 
move .w #9,-(sp) 
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trap U 1 

un L k a6 


/Restore A 6 




move. I #1,d0 /store the value to be returned in DO 
rts /end of the function/ return to Hi Soft C 

The u n l k instruction restores the A6 and stack registers to their w 
original values. 

The value returned by the function must be stored in DO. In our 
example the value returned is always 1 . This value is recovered by the 
interpreted C program. 

If the function returns a double precision 8 byte number then this is 
taken from DO and D 1 . 


Finally the RTS instruction finishes the function. 

To produce an executable program you must assemble it to produce a 
standard executable file with just the above instructions. You can if 
you wish link with your assembly libraries (like the GEM ones 
supplied with DevpacST) but don’t forget the following golden rules: 

• the first instruction in the executable file must be the first 
instruction in the function. 

• the function must finish with an RTS. 

• don’t mess with the base page. 


1.10.5 Compiled C functions 


This section describes how to use compiled C functions in your 
HiSoft C program. W 

As with assembler the C function must be at the very start of the 
module. The assembler example above is the following in C: 

^include <osbind.h> 

writ(str1,str2) 
char *str1, * s t r 2 / 

{ 

CconwsCstrl )/ 

Cconws(str2)/ 
return ( 1 ) / 

> 

The procedure writ is the first in the module; it does exactly the w 
same thing as the little assembly language program. 


Page 48 


HiSoft C 


Using HiSoft C 


To turn this into an executable file that HiSoft C can understand you 
must of course compile and link this function. But you must not 
include the ‘startup’ code in you program. 

With most C compilers you explicitly link with this startup module. 
With Lattice C 5 this module is called C . 0 . With Lattice C 3, it was 
called STARTUP.BIN, and with Megamax C it is I N I T . 0 . You must 
not link with any of these files. Remove the startup file from the file 
list that is used when you link. Your program will now be the first in 
the list. 

With Aztec C, things are slightly easier, just compile with the + B 
option. This will remove the reference to the .begin label, so the 
start up code won’t automatically be included. 

Although you. mustn’t link with the usual startup code you can use 
the normal libraries (C, Gem etc). 

So you produce a . P R G file, but one that cannot be directly executed 
by your ST because it does not have the correct initialisation. This is 
the file that you can load under HiSoft C. 


1.10.6 Loading executable procedures. 

Project Files. 

A project file consists of commands telling HiSoft C which files make 
up a project and thus which files must be loaded. 

These files are of two types: interpreted C files and executable code 
files. 

The project file consists of a series of lines. 

If a line starts with a hash character (#), the line is treated as a 
comment and ignored. 

If a line starts with a dollar ($), it is a command. 

If not, it is a file name. 
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The commands are as follows: 


$REP <di rectory name> Specifies the directory in which the 

files are stored. You may have several 
of these in the same project file. 

SC Specifies that the following files are 

the C files to be loaded. These files will 
be treated as interpreted C. 

SASM Indicates that the following filenames 

are those of executable files to be 
loaded by HiSoft C. 

$32 and $64 Only relevant for executable files. They 

give the size of the value returned by 
the function stored within the 
executable file .This size is 32 bits by 
default for integers, characters, 
pointers etc. This size must be 64 bits 
for functions that return a double 
precision real number. 


You may have several $C and $ASM commands in one project file. 
Here is an example project file: 


#========================================================== 

ft 

ft Project Description File 

n 

#========================================================== 

ft First part (optional) : $REP specifies the directory (le 
U repertoire!) to load the files from. This $REP directive 
ft may occur several times in the file. 

U 

$ R E P D:\HC\EXAMPLES 
ft 

#========================================================== 

ft Second part (optional) : 

ft C source files to load for HiSoft C to load. 
ft No more than 8 C files may be loaded 

ft The list of files must be entered after the $C directive 
ft one file per line. 

$C 

f i 1 1 . c 
# 
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V/ 




U Third stage (optional) : 

U Machine code files to load 

U Note that their format is special and is not that of 
standard 

U executable f i les . 

U No more than 200 (!) may be loaded 

U The list of files must be entered after the SC directive 

# one f i le per line. 

U 

// $32 indicates that the functions return a 32 bit value 

# (char, short, int or long). 

# $64 indicates that the functions return a 64 bit double 

# value 
U 

$ASM 

$32 

f i l l . cod 


This file describes a veiy simple project containing only one C file fill.C 
and one executable file fill. cod. 




Both files are stored in D:\HC\EXAMPLES. 


The fill function is supposed to return a 32 bit value (the default 
case). This is also a sensible value to use for all functions that do not 
return values. If the function returns a double precision real value 
then you must specify $64. 

V When you select the option Load project from the Run menu all the 
files mentioned in the project file are loaded into memory. 

r 

1.10.7 Calling executable functions 

An executable function that you load and call in a C program must be 
declared as extern. For example, the following line must be placed in 
the interpreted C program in order to use the fill function: 

, extern void fill(); 


An executable function may have parameters and may return a value. 
The definition and call are in the traditional C style. 




1.10.8 Project Information 


When you click on the Info about project item from the Run menu a 
list of loaded executable files appears on the screen together with the 
type returned by the function (32 or 64 bits). 
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1.11 The Disk Utilities 


1.11.1 Loading the utilities 


Disk Utilities is a program that can be loaded at the same time as the 
Interpreter and be co-resident in memoiy. You can switch between 
the disk utilities and the interpreter instantly to perform various 
operations on files and directories (copying, duplicating, deletion) 
and disks (formatting, information). When you return to HiSoft C 
you will be in exactly the same state as when you left. You can thus 
work with your files and disk without returning to the Desktop. 

However, naturally the Disk Utilities use some memory. If you have 
512K memory, you only have a limited amount of memoiy when 
using HiSoft C and loading the utility will reduce this further. 

So you can decide whether to load the Disk Utility depending on how 
much memory you need. 

If you have 512K, HiSoft C will not load the Disk Utility by default. 
This gives a ‘decent’ amount of usable memory for writing C 
programs. 

If you have more than 512k the utility will automatically be loaded. It 
is available for use the moment that the interpreter has loaded. 

However, you can change the default. 

To load the disk utility you should select the Load disk util option 
from the Help menu. When a tick mark is present, every time you 
load HiSoft C, it will load the utility as well. If you remove the tick by 
selecting the menu item again then the utility is not loaded and your 
programs can use the memory that it would otherwise use. 

After selecting Load Utilties you should save the options and re-load 
HiSoft C. This is how HiSoft C remembers your choice. Then each 
time you load the interpreter HiSoft C will load or not load the utility 
as you have asked. 
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1.1 1.2 Using the Utilities 


When you click on Disk utilities, the screen is cleared and a new menu 
appears. There is only one menu, called Options. 

The menu item Return to HiSoft C does just that: it takes you back to 
the interpreter. 

The Format command produces a dialog box like this: 



You can use this to format a disk, single- or double-sided, and specify 
several parameters (the number of sectors per track and the number 
of tracks per side) which will give you a little extra space on your 
disks. You may also indicate whether you want to verify that the disk 
has been formatted successfully. Clicking on Format will bring up a 
confirmation box and then format your disk. 
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The File Selector option brings up a dialog box like this: 


Options 



The two selectors display the files on the current drive (normally A) 
when HiSoft C was loaded. To change drive, just click one of the 
buttons at the top of the screen that indicate which drives are 
available. 


To select a particular folder or directory just double-click on its name. 
To return to the parent of this directory double-click on the directory 
called " - - " . 

By default, all the files in a directory are displayed; a selection of files 
can be displayed by choosing one of the ‘filters’ near the middle of the 
screen. To display just the . C files click on the button * . C. 

The two windows can display the contents of different files or 
directories. To switch between windows, click on the appropriate 
window’s title or information bar. 


To delete or rename a file select the appropriate file and click on the 
DELETE or rename button. To copy or move a file, set up the 
destination directory (where the file will be copied or moved to) in one 
window and then select the file to copy in the other window. To 
perform the copy or move click on the appropriate button, move is 
just like COPY except that the original file is deleted. 

You may copy, move, delete or rename more than one file at once, just 
hold a Shift key down when clicking on a file; any currently selected 
files will remain selected. 
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You can find out how much used and free space there is on a 
particular drive by double-clicking on the appropriate drive button. 

Finally, to create a new folder, first select the folder in which you 
want the new one to appear and then click on the new folder 
button. You will then be prompted to enter the name of the new 
folder. 


1 



v_> 






v 
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2 Introduction to the C 
language 


This introduction to the C language is designed for people with some 
programming experience. We assume that you know and are familiar 
with the fundamental ideas of programs, statements, variables, 
conditionals and loops. 

Some knowledge of the BASIC language is useful for this section as 
we will make comparisons with BASIC. 

This is designed as a practical tutorial. There are a number of 
exercises and example problems. Appendix A contains answers to 
the exercises and suggestions for solutions. Note that certain ideas 
are discussed in the answers to the exercises. If you don’t read the 
answers you will miss some vital information. 

This section does not attempt to be a complete C language course but 
it nevertheless covers the working of a number of simple programs. 


v. 


2.1 Your first program 




2.1.1 The traditional approach 




v. 


In just about every introduction to a programming language, the first 
program is one to display hello on the screen. So to follow the 
tradition of many generations of programmers, here is a C program 
that displays Hello and then How are you? on the screen and 
then waits for a key to be pressed. 


m a i n ( ) 
i 

printfC" Hello\n" ); 
printf("How are you ? \ n " ) ; 
printfC" press a k e y \ n " ) ; 
evnt_keybd(); 

v. > 

That’s it. It seems a bit more complicated than in BASIC. 


L. 
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2.1.2 The big moment 


Load HiSoft C if you haven’t already. 

It’s waiting for you to type a program - go to it! 

If you have problems typing the program, see Section 1 , the section 
describing the editor. 

Always type carefully. In the C language upper and lower case letters 
are treated differently. The language keywords are always written in 
lower case. Two identifiers (variables or functions) made up of the 
same letters, one in capitals and one in lower case are different. Thus 
the names language and Language are not the same. You can’t use 
one in place of the other. 

Now that you have entered this example, the only thing left is to run 
it. To do this, click on the Run item on the Run menu. That’s it. 

Now let’s look at the program more closely. 


2.1.3 Functions, the fundamental unit in C 


A program written in C is made up of functions. They are the bricks 
from which a program is built. 

One of these functions has a special role; it’s called main. 

This function is essential because main is where the program starts 
executing. If there is no ma i n function the program can’t run. 

The whole C program is built around this function. You can have 
other functions as well as main and these are called from the 
function main. 

Keeping to this rule, the example above has a main function. 
Obviously it is the only function present in this program. So our first 
program is very simple in this sense although it may still seem 
complicated with its funny names and punctuation. 

Strictly, a function is a set of statements enclosed in curly brackets 
and preceded by the function name. 

The name of the function is followed by two round brackets 
(parentheses). This is explained in more detail below. 
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2.1.4 Statements 


A function is made up of statements which must always be 
terminated by a semi-colon(; ). The semi-colon indicates that the 
statement is over. It is similar to the colon(:) in BASIC, but in C every 
instruction is terminated by a semi-colon even if it is the only one on 
the line. 


2.1.5 The C library 


Our example has four statements, they are: 

printf( M hello\n" ); 
printf("How are you ? \ n " ) ; 
printf( M press a key\n" ); 
evn t_keybd ( ) ; 

printf and evnt_keybd are functions from the C library (yes, 
functions again, well we warned you!). That is to say they have 
already been written for ease of use. All implementations of C have 
their own libraiy of functions. They are invisible but very important. 
HiSoft C has over 460 of them. 

If 460 functions isn’t enough you can, of course, write your own. You 
have already started to write a function main. In fact there’s no 
fundamental difference between libraiy functions and those that you 
have written. Only that those in the libraiy have been written already 
(in C of course) and you have to create your own functions yourself. 


2.1.6 Calling Functions 

Amongst the library functions are evnt_keybd which waits for a 
key to be pressed (short for keyboard event) and printf which 
displays a string of characters on the screen. The string is passed to 
the printf function. The values that are passed to functions are 
called the parameters or arguments of the function. The list of 
parameters to pass are given enclosed in round brackets. To conform 
to this rule the strings in our example are enclosed in parentheses in 
order to pass them to the function. 

A function may have one, several, or no parameters. In our example 
the printf function has a single parameter. The main and 
evnt_keybd functions don’t have any parameters. This is why the 
names main and event_keybd are followed by parentheses. We 
haven’t seen any functions with several parameters yet. In this case 
the arguments are separated by commas. 
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2.1.7 Strings 


A string is a collection of characters enclosed in double quote signs. 
What ever it contains a string is a valid element in language. The 
following are legal strings: 

"Hello" 


and 


"How are you ?" 

In our program we added the two characters \ n at the end of the 
string just before the closing quotes. These two characters form one 
unit and mean together “newline". On the ST this means carriage 
return and line feed. So because of the \n in our example How are 
you ? is on the line below hello. 

Exercise 1 

Produce the following display on the screen: 


h e 

llo How are 
you ? 

and follow this with a message asking for a key press. There is 
no need to use any extra p r i n t f statements. 

Exercise 2 

Try to run this program after deleting a few characters to see 
what error messages they produce. 
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2.2 Variables 


2.2.1 One more program 


Here’s a program that reads a key from the keyboard and displays it 
on the screen. Then the program waits for another key before it 
terminates: 

intch; 
m a i n ( ) 

•C 

ch = evn t_keybd ( ) ; 

putchar(ch); 

evnt_keybd(); 

> 

Before typing this program, you must first delete the last program 
that you’ve already typed. All you need to do is select Abandon from 
the File menu. This is equivalent to New in BASIC. 

Ok, so now type in this program and execute it by clicking on Run. 
Press a key on the keyboard and the corresponding character will be 
displayed on the screen. Press a key again and you’ll be back in the 
editor. 


2.2.2 Function or Statement ? 


In C a function always returns a value. This is sometimes ignored by 
the programmer. However, the evnt_keybd() function can be used 
either as if it were a statement: 

evn t_keybd ( ) ; 

or as if it were a function. That is to say it can be treated as a routine 
that returns a value (the ASCII value of the key pressed in the case of 
e vn t__keybd ( )), like this: 

ch = evnt_keybd(); 
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2.2.3 Assignment 


This last instruction assigns to the variable called c h , the value 
returned by evnt_keybd. The variable ch then contains the ASCII 
code of the key that was pressed. The symbol = is the assignment 
operator as in BASIC. Also, like BASIC 

1 = 1 ; 

gives the variable i the value 1 . We’re on familiar, friendly territory 
here. But there are mines ahead! 


2.2.4 The putchar function 


The statement 

putchar(ch); 

writes the character whose ASCII code is stored in the variable c h . 
put cha r is a C library function like pri ntf or evnt_keybd. It has 
one parameter that is the character to display. 


2.2.5 Declaring variables 


Well, we left the best bit until the end. In C, every variable must be 
declared before it is used. This is so the user can indicate what type is 
associated with each variable. 

In BASIC, variables are reals by default, integers are followed by % 
and string variables by S. Modem BASICS also let you use ! to 
indicate single precision and U double precision. 

This is how BASIC knows the type of each variable. In C it is totally 
different. 

A scheme like that used by BASIC is impossible because there are so 
many types (in fact, there’s theoretically an infinite number). The 
user must declare his or her variables, i.e. specify the type, before 
they axe used. A variable may be a whole number or a real etc. This 
procedure seems fussy at first, it requires more thought when 
defining variables but means that some errors can be detected that 
otherwise wouldn’t be, mis- spellings in particular. 


Page 62 


HiSoft C 


C Language Introduction 


2.2.6 Integers 


We now know that all variables must be declared before they are used 
and that this declaration specifies the type of the variable. In our 
example, the declaration of the variable c h is 

i n t c h ; 

The keyword i n t is short for integer. So the statement above makes 
c h an integer. We say that c h is declared as type integer. 

In HiSoft C integers are signed and use 4 bytes of storage. 

An integer variable may therefore contain values between 
-2147483648 and +2147483647, which is quite enough for most 
purposes. 

The type i nt is probably the most frequently used in C. But there are 
others. 

Whole numbers will often fit into only two bytes. This is the type 
short. It’s the equivalent to integers in most BASICS. The range of 
values is -32768 to 32767. 

We can make our variable c h of type short because a character code 
can be between 0 and 255, which is entirely within -32768 to 32767. 
We do this as follows: 

short ch; 

So this makes ch a short integer. This is the only change needed in 
the program because the ASCII code for the character can be 
represented by a short integer. 

There are also whole numbers that fit into just one byte. This is the 
amount of storage needed for a character. For this type, the variables 
may take values between 0 and 255. This type is sensibly enough 
called c h a r . So to indicate that c h is of type char all we have to do is 
use 


char c h ; 

and the program will work just as well. 

We used the type i n t for c h to start with because this is more or less 
right, but it looks more elegant to declare it as type char. The 
difference between these three integer types is only a question of size; 
they are all integers. 
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2.2.7 Real numbers 


HiSoft C supports real or floating point numbers. These are always 
double precision. Their values can vary between -1.8 E 308 and 1.8 E 
308, and can be as small as 1 E -307 without being zero. They have 16 
significant digits and use eight bytes of storage. The type of these 
numbers is float or d o u b l e . As far as HiSoft C is concerned they 
are equivalent. The declarations of real numbers look like this: 


float x; 
double f l ; 

These two lines declare variables x and f l of real type, float and 
double are exactly the same type. 


Floats aren’t often used in C. Integers are used much more 
frequently, although engineers tend to use floats a lot! 

2.2.8 Conclusion and Exercises 

We have seen in this example how to use integer variables in C. 

The types discussed above are the primary types. We can also 
construct arrays, structures and pointers based on these four types. 

Exercise 3 


Write a program which waits for two keys to be pressed and 
then writes the two characters on the screen. You should declare two 
variables. 
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2.3 Calculations 


c 

u 

c 


2.3.1 A little program 


Try the following little program: 

/* Examples of calculations with reals */ 
double real; 
i n t whole; 
short small; 
m a i n ( ) 

whole = 1 + 56; 

small = whole/2; 

real = 10.2+2*small+sin(2.); 

> 

This example doesn’t include much that is new. It just puts into 
practice what we have already seen. 




2.3.2 Comments 


You can add comments to your programs. Comments start with /* 
and finish with * / . Between these two pairs of characters anything 
goes. However a comment must fit on a single line (this is a HiSoft C 
restriction because it is an interpreter). 


Comments are normally placed between statements and frequently 
at the ends of lines, whether they are empty or not. 




c- 


2.3.3 Arithmetic operators 


The C language has the following binary operators: 


* 

multiplication 

/ 

division 

% modulus 

+ 

addition 

- 

subtraction 


These operators act on the two items to either side of the operator 
following the usual rules. 
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The modulus operator is the remainder when the first operand is 
divided by the second. Both arguments must be integers in this case. 
For the other four operators the arguments can be integers or reals. 

The following priority rules hold: 

The operators multiplication (*), division (/) and modulus (%) all have 
the same priority which is higher than the addition (+) and 
subtraction operators ( -). These rules are the same in most 
languages, BASIC included. 

Note that there are many other operators that we will cover later. 


2.3.4 The arithmetic and trig functions 


In our example, we used the function s i n which calculates the sine 
function of the argument that it is passed. This argument must be 
expressed in radians. This is only one of the trigonometric functions 
available. Here’s the full list: 

cos, sin, tan, atan, Log, exp, sqr, asin, acos, floor 

These function all take one compulsory parameter of type double. 
They return real values equal to the cosine (cos), sine (sin) tangent 
(tan), arctangent (atan), natural logarithm (Log), natural anti-log 
(exp), square root (sqr), arc-sine (asin), arc-cosine (acos) or the 
whole number part (floor) of the argument. 

If you want to pass a whole number, for example to find the 
logarithm of 5, you must follow the parameter with a decimal point to 
indicate that the number is really a floating point number. Otherwise 
you will be in for a surprise. For example, 

l o g ( 5 . ) + s i n C 2 . ) ; 


2.3.5 Types and assignments 


Returning to our example, 

double real; 
i n t whole; 
short small; 

The first three lines declare the three variables that we need in the 
program, real is a real number, whole is an integer and small is a 
short integer. 
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c 

c 


whole = 1+56; 
small = whole/2; 

The first statement stores the value 57 in the variable whole. Then 
whole is divided by 2 and this value stored in the variable small. 

whole and small aren’t of the same type. But there is no problem 
assigning an int variable to a short one. More generally it doesn’t 
matter which of the integer types (int, short or char) you assign to 
another integer variable. The only problem is that the value may have 
to be truncated. This is the case if you try to store 350 in a variable of 
type char which can’t hold a value bigger than 255. No error 
message will be given but the value stored will be equal to 350 modulo 
256. 


The division of w h o l e by 2 is an integer division because whole and 2 
are both integers. As whole is 57, who l e / 2 is 26 and not 26.5. 

In general, within expressions where all the terms are integers, the 
+ and / operators are all treated as integer operators and return 
whole numbers. 




Vw 




If, on the other hand, at least one of the terms in an expression is a 
real, all the other terms are converted to floating point numbers and 
+,-,* and / are used as real operators. 

This is what happens in the third statement: 

rea l = 10.2+2*small+sin(2.); 

The terms 10.2 and sine(2. ) are reals so the other terms in the 
expression (2 and small) are converted to reals. 

Then the calculations are performed and they return a real value 
which is assigned to the variable real. Thus a floating point 
expression is assigned to a floating point variable. In fact both sides 
of an assignment must be of the same type, that is to say, either both 
integer or both floating point. If you want to break this rule, you will 
need to use the explicit type conversions (see your favourite book on 
C). 


w 

c 
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2.4 Conditionals 


2.4.1 Example 


In C, like in BASIC, there is a conditional statement that lets you 
execute a series of instructions if a particular condition is true. 


Type the following program: 


i n t num; 
m a i n ( ) 


num); 

> 


num = Random (); 
if ((num / 2 ) * 2 = = 

printf(" The 

evnt_keybd( ); 


num) 

number 


%d 


is even\n", 


The example uses the variable called num. It is declared in the first line 
of the program and is of type i n t or integer. 


2.4.2 The Random function 


Random is a function from the BIOS library (see Chapter 4 for a 
description). Note that the first letter of this identifier is in upper 
case and that all the others are in lower case. This is a convention 
used by Atari for all the BIOS functions, so we use it too. 

Right, back to where we were. Random returns a random number! It’s 
a 24 bit positive whole number, that is between 0 and 16777215. 

In the example, the random number is stored in the variable num. So 
we have an unknown value in n um. 


2.4.3 The if statement 


We now suppose that we want to know whether this number is odd 
or even. The mathematical definition is that a number is even if it is 
divisible by two. More precisely a number, num, is even if (num/2)*2 
is equal to num where the division is integer division. 
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We can write this algorithm in the form: 

If (num/2)*2 is equal to num then 

write “the number ‘num’ is even” 

In C this becomes: 

if ((num / 2 ) *2 == num) 

printf("The number %d is even\n", num); 

The i f statement has the form: 

if (condition) 

statement; 

The condition, which must be enclosed in round brackets, is 
evaluated. If this is true then the given statement is executed. If the 
condition is false then the statement is not executed and the 
program continues executing at the following instruction. 

One small detail. To test if two expressions are equal we use the two 
characters ==. In BASIC only one equal sign is used. But two is better 
than one ... 

There are other comparison operators: 


1 s 

not equal 

< 

less than 

> 

greater than 

< = 

less than or equal 

> = 

greater than or equal 

= = 

equal 


For example, the condition that tests if the two terms (num/2)*2 
and num are different is 

( num/2 ) *2 ! = num 

There are also logical operators so that you can test several 
conditions at the same time. These are equivalent to BASIC’s AND, 
OR and NOT keywords. 


1 1 


Logical OR between two conditions 

& St 

And 

Logical AND between two conditions 

i 

NOT 

Negation of a condition 


These operators will be discussed further in future examples. 
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2.4.4 printf... again 


Thus if our number is by chance even, then the printf statement is 
executed. 

We have already encountered printf, but that was in its most 
simple form. We have only had one parameter. Now there are two and 
also there’s a strange % d in the string. 

The two characters % d in the string "The number %d is even\n" 
indicates where to insert the number nurm in the output to the screen. 
For example, if num is 256 then the instruction: 

printf("The number %d is even\n" , num); 

writes on the screen: 

The number 256 is even 

So the value of the variable n u m is sent in place of the % d . The % d is 
powerful if cryptic, isn’t it? 

Thus %d replaces an integer value in the string. That’s it. Does it seem 
complicated? Well, its like that regardless! 

More seriously, you can write several variables with the printf 
function. For example here’s an instruction that writes the values of 
the three variables v 1 , v 2 and v 3 : 

printfC" Here are three values : %d, %d and 

%d",v1,v2,v3); 

If these three variables are 1, 2 and 3 respectively then this will 
display: 

Here are three values : 1, 2 and 3 

You will have noticed that there are three lots of % d in the string and 
also three variables to write. The three variables are substituted for 
the three %d’s left to right. 

The first variable (vl) is substituted for the first %d and so on. 

Exercise 4 

Write a program (complete with variable declarations and so on) 
which lets you see the three variables above. 
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2.4.5 if. ..else... 


Even the simplest of machines have BASIC IF... THEN... ELSE... 
statements nowadays, and C doesn’t stop there. 

Let’s improve our previous program. 

In the last example a message was only displayed if the number was 
even but not if it was odd. Now let’s have a message if it was odd as 
well. 


i n t num; 
m a i n ( ) 

num = Random (); 
if (num%2 == 1) 

printfC" The 

else 


> 


printfC" The 
evnt_keybd(); 


number 

number 


%d 
% d 


is o d d \ n " , n ) ; 
is even\n" , n); 


The algorithm for this program is simple: 

Make num a random number, 
if num is odd 

then write “The number ‘num’ is even” 
if not 

write “The number ‘num’ is even” 
Wait for a key press. 

The form of the if... else instruction is 


if (condition) 

statementl ; 

else 

statement2; 

The expression, which must be enclosed in parentheses, is evaluated. 
If the condition is true then statementl is executed. If the 
condition is false, statementl is not executed but statement2 is 
executed instead. 

Examine the program in detail. There’s a new little bit in the 
condition of the if. We use the modulus or remainder operator which 
is written as % in C. A number is even if its remainder when divided by 
two is 0. It’s odd if the remainder is 1 . 
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If the condition is true, that is to say the number is odd, then the 
first of the two p r i n t f statements is executed. Thus we could get: 

The number 257 is odd 

If the condition is false then the second instruction is executed: 

The number 256 is even 


2.4.6 Blocks 


The examples we have seen so far only let you execute a single 
statement conditionally with i f . Thus the syntax is: 

if (condition) 

statement; 


and not 

if (condition) 

statementl ; 
statement2; 
statement3; 

What happens if you want to execute more than one instruction in 
the body of an i f ? 

Answer: There’s a structure that is always considered as a single 
statement but (and this is its secret) actually contains several 
statements. 

This groups several statements into a block. A block can be put 
anywhere that you can put a single statement. Anywhere you see a 
statement in a syntax description you can put a block instead. 

In practice, a block is a set of statements (followed by semi-colons as 
usual) and surrounded by curly brackets. Here’s a block consisting of 
two printf statements: 

printf(" Hi! " ) ; 
printf(" How are you ? " ) ; 

> 
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'w 

;C 

iU 


Note that the curly brackets surrounding the block are on lines by 
themselves and the statements are on separate lines. This is to make 
it more readable. However, this layout is not compulsory. The block 
above is equivalent to: 

■CprintfC" Hi! " );printf(" How are you?");) 

The first block is more readable but the second is quicker to type. 

Now that you know (we hope) what a block is, the syntax for an i f 
statement can be written: 

if (condition) 

statement; 

statement; / * etc... * / 

> 

else 

statement; 

statement; / * etc... * / 

> 


This uses the rule that a block can replace any instruction and vice 
_ versa. 


The following sequence is equally correct. 






if (condition) 

statement; 

else 

statement; 

statement; 

> 

Note that a block can contain just one statement. 


Exercise 5 

Write a program that generates an even random number from some 
random number. The program should display neatly whether the 
initial random number is odd or even. If it is already even it should be 
left as it is. 
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2.5 Loops 


Loops enable you to execute the same sequence of statements several 
times. 

In old-style BASIC there is only one sort of loop. Everyone knows the 
famous FOR... TO... NEXT statement. There’s a similar statement in C 
called for. 

In slightly more modem BASIC’s there’s a WHILE... WEND loop. This 
executes a particular set of statements while a condition is true. This 
statement is also called wh i l e in C. 

Finally there’s a third statement which is a variant on the w h i L e 
statement called d o . . . w h i L e . 


2.5.1 The while statement 


Type and run the following program: 

i n t i ; 
m a i n ( ) 
i 

i = 1; 

while (i <= 20) 

printfC" %d squared is %d\n", i, i * i ) ; 
i = i + 1 ; 

> 

evn t_keybd ( ) ; 

> 

If you have followed the previous section you can probably guess 
what this program does. 

It finds the squares of all the numbers between 1 and 20. 

The algorithm used by this program is: 

initialise the number to one. 
while the number is less than 20 do 
write the square of the number 
add one to the number 
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Let’s look at this program in detail. 

The variable i is declared in the first line as of type integer. The first 
statement in the program is i = 1 ; which stores the value 1 in the 
variable i . 

The while statement repeatedly executes the block containing the 
following two statements: 

printfC" %d squared is % d \ n " , i, i * i ) ; 
i = i + 1 ; 

> 

while the condition i < = 2 0 is true. The two statements are repeated 
twenty times during the execution of the program to write the 
twenty squares on the screen. 

The syntax of w h i l e statements is 

whi le(condition) 
statement; 


or 

whi le(condition) 
statement; 

statement; /* etc.-.*/ 

> 

The one or more statements that form the body of the while 
statement are executed whilst the condition is true. 

The two groups of % d in the mysterious p r i n t f statement insert the 
values of i and i * i in the string to be output. This follows the rules 
we have seen in Section 2.4.4. 

The statement i = i + 1 adds the value 1 to the variable i , just like 
you would write in BASIC. 

The statement evnt_keybd waits for a key to be pressed on the 
keyboard. 
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Note that if the condition in a while statement is false on entry the 
statements in the loop aren’t executed at all, as in the following 
program: 

i n t i ; 
m a i n ( ) 

i = 
w h i 


> 

> 

Exercise 6 

The example above writes the first twenty squares in increasing 
order. Write a program which writes the squares of whole numbers 
starting with 20 and finishing with 1 . 


5; 

l e ( i <4 ) 

printfC" toto"); 
i + + ; 


2.5.2 The for statement 


In BASIC the FOR... NEXT statement uses a loop counter variable. 
When the said variable reaches a certain value the program stops 
executing the statements between the FOR and NEXT statements. 
It’s nearly the same in C. 

The following program writes the squares of the numbers between 1 
and twenty that we’ve already seen using a for statement. 

i n t i ; 
m a i n ( ) 

■C 

for (i = 1; i <= 20; i = i + 1) 

printfC" %d squared is %d\n" , i, i * i ) ; 
evnt_keybd( ); 

> 

This example is exactly equivalent to the previous one. To prove it, 
run it! 

The algorithm for this program is as follows: 

Varying i from 1 to 20 in steps of 1 do 
write the square of i 
Wait for a key press 
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In BASIC this corresponds to 

FOR 1=1 TO 20 

PRINT I;" squared is" ; I * I 

NEXT I 
A $ = INKEYS 

V 

if we remember BASIC correctly. 


c 




In detail, the C syntax for for statements is 

for (statementl; condition; statement2) 
statement3 ; 
rest of the program; 

or alternatively 

for (statementl; condition; statement2) 
statement3; 

statement4; / * etc-.- * / 

> 

rest of program; 

When HiSoft C comes across such a statement, it does the following: 

It executes statementl first of all (i = 1 ). Next it evaluates the 
condition ( i < = 2 0) . 

If this is false, HiSoft C starts executing the rest of the program. If, 
however, the condition is true, HiSoft C executes statements then 
statement^., which constitutes the body of the for statement 
(p r i n t f ...) 




Finally statement2 is executed (i=i + 1). 
The condition is evaluated once more. 


If it is false, HiSoft C executes the rest of the program. But if it is still 
'w true, HiSoft C executes statements, statement4 and then 
statement2 again. The condition is evaluated once more... 

But perhaps we are repeating ourselves. 

Looking at it another way, statementl is executed. Then the body 
statements followed by statement2 while the condition is true. 
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So the statement above is exactly equivalent to: 

statement*!; 
whi Le(condition) 

statement3; 

statement4; 

statement2; 

> 

rest of the program; 

Note the numbering of the statements. 

Exercise 7 

This is the same as the last one. Rewrite the program above (with the 
for statement) so that it writes the squares in reverse order using a 
for statement. 

Exercise 8 

Write a program which finds the sum of the whole numbers between 
1 and 100. 

Exercise 9 

Write a program that displays the ASCII character set. Remember 
that putchar(ch) writes the character whose code is in the variable 
ch. 


2.5.3 The do. ..while statement 


This loop structure is used less often than the two previous ones. It is 
based on the while statement and resembles it a lot. 

char c h ; 
ma i n ( ) 
i 

d o 

ch = evn t_keybd ( ) ; 
putchar(ch); 

> 

while (ch != 13); 

> 

A character is read from the keyboard, stored in the variable c h, then 
written to the screen. This is repeated until the character read is a 
Return (ASCII code 13). 
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c 

C 

c 




The syntax of the do . . . wh i l e statement is as follows: 
d o 

statement; 
white (condition); 

or 

d o 
{ 

statementl ; 
statement2; 

statement3; /* etc... */ 

> 

whi te(condition); 

Note the semi-colon after the while (condition);. 

The statements are executed while the condition is true. 

The difference between the = statement that we saw above and this 
one is that the body of the statement is executed first and then the 
condition is evaluated. If it is true, then the program continues to 
loop. If not, the do . . . wh i l e loop finishes. 

In the standard while loop the condition is tested before the body 
statements. As a result, with a do . . . wh i l e the body statement is 
always executed at least once, whereas with the while statement it 
may never be executed. 




2.6 Switch statements 


A switch lets you execute one of several statements depending on a 
condition. For example, if a variable or expression has one of several 
values. 


The statements that are executed are different depending on the 

\ value. This is equivalent to the SELECT CASE statement in HiSoft 

BASIC. 

Let’s take a simple slot machine as an example. 

A number between 0 and 9 is chosen by chance. If you get a number 5 
or 7 you win. 7 is the jackpot. If you get a 6 you lose. 
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The algorithm is: 

Select a number by chance 

Depending on the number 
if it is 6 

write “you have lost” 
if it is 7 

write “Jackpot” 
if it is 5 or 7 

write “you have won” 
other values 

write “you haven’t won or lost” 
Translated into C this becomes: 


i n t num; 
m a i n ( ) 

•C 

printfC" Put a lOp coin in the sLot\n" ); 

evn t__keybd ( ) ; 

num = RandomC) % 10; 

switch (num) 


case 6 : 

printfC "You have got 6 \ n " ) ; 
printfC "You've L o s t \ n " ) ; 
break ; 

case 7 : 

printfC "You have got 7\n"); 
printfC " JackpotXn" ); 

case 5 : 

printfC "You have won\n"); 
break ; 
default : 

printfC "You have got %d\n", 
printfC "and have neither won 
break ; 

> 

evnt_keybd( ); 

> 


num); 

nor 


l os t \ n " ) ; 


Let’s examine this program in detail. 


The variable num is an integer which contains the number chosen by 
chance. 


To obtain this, we use the function Random to return a whole random 
number. We take this value modulo 10 to make it a random number 
between 0 and 9. 
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Then we come to the interesting bit of this example. 

It’s the s w i t c h statement. Swi tch executes one of several 
statements depending on an integer value. The expression is 
evaluated and then compared with a list of constants. When a match 
is found execution starts with the corresponding statement. 

In our example, the said expression is the variable num. Depending on 
the value of this variable we know whether you have won or lost 
because number contains the value that was chosen by chance. 








In C, the phrase “if it is 6” translates to case 6 : . Don’t forget the 
colon. 

Thus if the variable has the value 6 then the two statements: 

printfC "You have got 6\n" ); 
printfC "You've Lost\n" ); 

which follow case 6 : are executed. 

Just after these two statements is the keyword break. This means 
in this case (if num=6) the switch statement is finished. 

Thus if the value is 6 the messages are written on the screen and you 
have lost. 

Now, we’ll look at the next case. It’s the value 7; good news, it’s the 
jackpot and the appropriate message is written in the screen. 

printfC "You have got 7 \ n " ) ; 
printfC" Jackpot\n" ); 

Next it’s the turn of 5. You’ve won but not the jackpot. So just the fact 
that you have won is displayed. 


printfC" You have won\n"); 

Immediately afterwards there’s a break statement which tells us 
that the switch statement is over and the rest of the program is 
executed. 

If you have been paying close attention, you will have noticed that 
there is no break statement after case 7 . 
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Let’s take another look: 

C g s 6 7 : 

printfC" You have got 7\n"); 
printfC" Jackpot\n" ); 

case 5 : 

printfC" You have won\n" ) ; 
break ; 


A 7 has been chosen. HiSoft C executes the two p r i n t f statements 
after case 7. But there’s no break to tell the interpreter to stop, so 
it continues and executes the statement printfC" You have 
wo n \ n " ) ; from case 5. After that, there’s a break statement so the 
switch is finished. The next statement in the program will then be 
executed (e ven t_keybd C )). 

The last part of the switch statement is default:. This is a special 
possible switch value that is executed only if no match has been 
found. So in our slot machine program the following statements will 
be executed if our random number isn’t 5,6 or 7. 

printfC "You have got %d\n", num); 
printfC" and have neither won nor lost\n" ); 

Note that you don’t have to have a default in a switch statement. 
In this case if the swi t c h variable doesn’t match one of the other 
cases, no statements are executed as part of the switch. 

More rigorously, the switch syntax is as follows: 

switchCint_expression) 

case constant-1 : 

statement-1; 

break; 

case constant-2 : 

statement-2; 

statement-3; 

break; 

case constant-3: 

statement-4; 
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L. 


Sw 


case constant-4: 

statement-5; 


default: 

statement-6; 

statement-7; 

break; 

> 

So in English, this does the following: 

If the i n t _e x p r e s s i o n is equal to constant-1, then statement-1 
is executed. 

If the i n t__e xpressi on is equal to constant-2, then statement-2 
and statement-3 are executed. 

If the i n t ^expression is equal to constant-3, then statements 

4.5.6 and 7 are executed. 

If the int_e xpressi on is equal to constant-4, then statements 

5.6 and 7 are executed. 

If the i n t_e xpressi on is not equal to any of the constants 1,2,3 
or 4 then both statements 6 and 7 are executed. 

Note that the expression following switch is in parentheses, a case 
must be followed by a colon and all the case items are enclosed in 
curly brackets. 

Exercise 10 




C 


Write a program that reads a character from the keyboard, and then 
displays it if it is A or B, otherwise it displays an asterisk instead. 
Pressing the space bar should stop the program. You can use a 
switch statement or several i f statements. 


2.7 Functions 


2.7.1 Functions and subroutines 


At the start of this introduction to the C language we said that a C 
program is made up of one or more functions which are called from 
one another. The moment has come to prove it. 
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A function is a set of statements that are grouped together. 
Generally there is something linking these statements, that is to say 
they implement a particular operation. 

There are two sorts of functions: library functions and those that 
you write yourself. 

Library functions are subroutines that are already written and are 
available for your use. You’ve already used the libraiy functions called 
printf, putchar, and evnt_keybd. 

The functions that you write yourself are the equivalent of 
subroutines in BASIC that are called using GOSUB. (Actually they 
are more like SUB and DEF FNxx definitions in HiSoft BASIC). 

C functions have names of their own which are used to call them. In 
addition you can pass information between the calling program and 
the function. 

Let’s look at a concrete example. We shall create a function called 
wait. 

This will write “press a key" on the screen and wait for a key to be 
typed on the keyboard. This function is useful when you are 
displaying messages, as it gives the user plenty of time to read what 
is on the screen. 

m a i n ( ) 
i 

printf (" message 1 \ n " ) ; 
w a i t ( ) ; 

printfC" message 2 \ n " ) ; 
w a i t ( ) ; 

> 

w a i t ( ) 

printfC "Press a key\n"); 
evnt_ keybdC ); 

> 

The wait function consists of two statements. The first writes 
Press a key and the second waits for a key to be typed. 

The main function has four statements. When you run the program, 
these and only these are executed. The statements in the function 
wait are not executed unless they are called by the main function. 
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The program starts by displaying message 1 . Then it calls the 
function wait, which waits for a key to be pressed. After the user has 
typed a key, message 2 is displayed. The function wait completes 
the program and it terminates as soon as the user presses another 
key. 

So far functions seem just like GOSUB subroutines in BASIC. 
However functions are more powerful than that. For example, they 
can have parameters. 


2.7,2 Parameters 


Remember our function wait. Suppose we want to wait for a 
particular key, but it isn’t always the same one. For example, the first 
time we want to wait for the a key and the second time the b key. This 
is a little artificial, but better than nothing. 


There’s a neat solution using parameters: 


char ch; 
m a i n ( ) 

printfC" message 1 \ n " ) ; 
wa i t ( ' a ' ) ; 

printfC" message 2 \ n " ) ; 
w a i t ( ' b * ) ; 

> 


L 




w a i t ( c ) 

char c ; 

printfC "Press the %c key \ n " , c); 

d o 

ch = e vn t_key bd C ) ; 
while Cch != c); 

> 

The only real difference between this and the last program is the 
wait function. Now this function has a parameter which is the 
character that must be typed on the keyboard. 

The main function calls the wait function with a parameter ' a ' and 
then with a parameter ' b ’ . This indicates the key to wait for. Both of 
these values are the integers whose values are the ASCII codes for a 
and b. 

Inside the wait function the parameter is called c . This is a variable 
which contains the value that was passed as a parameter. During the 
two calls it takes the value of first ' a 1 and then ' b ' . 
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Be careful, the variable c can only be used in the wait function. All 
attempts to access it outside will be greeted with an error message. 
We say that c is a local variable of the function wait. 

You have learnt to declare all variables before using them, and 
parameters are no exception to this rule. They must be declared just 
after the name of the function and before the statements that make 
up the function. See the example. 

In our program, the variable c is of type char. This declares the 
variable inside the function; you can not access it outside its 
function, the wait function. Inside the wait function, we have a 
variable containing the character to wait for. 

The first statement in this function writes a message to the screen 
asking the user to press the appropriate key. 

Notice the bizarre % c inside the p r i n t f string. In a similar way to % d 
meaning ‘write an integer here’, %c means ‘write a character here’. So 
a character will appear on the screen rather than a whole number. 

The ASCII code of this character is in the variable c which was passed 
as a parameter. 

Thus, if c has the value 97 which is the ASCII code for the character 
' a ' , the statement: 

printfC" Press the %c key \n", c); 


displays 

Press the a key 

on the screen. If you change the %c to %d then 

printfC" Press the %d key \n", c); 

will show 

Press the 97 key 

Next, after indicating which is the key to wait for, HiSoft C executes 
the following loop: 

d o 

ch = e vn t_key bd ( ) ; 
while (ch != c); 

which reads a character from the keyboard (using evnt_keybd) 
whilst that character is different to the parameter of the function. 
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2.7.3 Return values 


A function may return a value to the calling program. For example, 
event_keybd sends back the code of the key that has been pressed. 

Let’s look at an example. Suppose we want to create a power function 
which raises a whole number to the power that it has been given. This 
function will be called from the main program in a couple of places to 
calculate 2 10 and 2 16 . The algorithm used will be a brute force one. 








The two parameters of this function are the number to raise and the 
power to raise it to. The value returned by this power function is the 
result of the calculation. 

int vallO; 
int v a 1 1 6 ; 
int result; 
ma i n ( ) 

•C 

vatIO = power(2, 10); 
val16 = power(2, 16); 

printf ("2 A 10 = %d, 2 A 16 = %d\n", vallO, val16); 
evn t_keybd ( ) ; 

> 




power (number, exponent) 
int number, exponent; 

result = number; 
while (exponent > 1) 

exponent — ; 
result *= number; 

> 

return (result); 

> 

The two integer variables vallO and v a 1 1 6 contain the result of the 
calculations of 2 10 and 2 16 . The main function stores 1024 in 
vallO and 65536 in v a 1 1 6 . The printf statement displays these 
values on the screen, thus, 

2 A 10=1024, 2 A 16=65536 

The power function has two parameters called number and 
exponent, and they are both declared as type integer. 
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The statement: 


exponent--; 

subtracts one from the variable exponent and the statement: 
result * = number; 
multiplies result by number. 

The variable result will thus contain the result of the calculation 
when the loop has finished. All it needs to do now is return this value 
to the calling program. This is done with the very simple statement: 

return (result); 

This statement stops execution of the function and returns control 
to the calling program. In addition, the value in parentheses is taken 
as the result of the function. 


2.7.4 Summary 


The general syntax of a function is as follows: 


function-name(arg'\, a r g 2 , . . ,,argn) 

type argl; 
type a r g 2 ; 

type argn; 

{ 

statement; 

statement; 

statement; 

return (expression); 

} 

f unct i on-name is the name of the function. 

arg1,arg2, argn are the arguments to the function. 

type is a type specifier (e.g. i nt,cha r, etc...) 

The characters in italics are compulsory, the others are optional. 

The arguments are optional. There may be none, one or several. But if 
there are any, then they must be declared. The parameter 
declarations must be after the list of arguments and before the 
opening bracket and statements of the function. 
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Exercise 1 1 


Write a function which does nothing, with no statements, and no 
parameters that is called from a main function which doesn’t do 
anything either. An exceptionally useful program... 

Exercise 12 

Write a program that reads two numbers from the keyboard and 
displays their sum. The get char function reads a character from 
the keyboard, echoing it and returns the ASCII code of the character. 
This is similar to our friend evnt_keybd except that getchar 
displays the character on the screen. To build up to this, write a 
function that reads a number from the keyboard where this may 
have several digits. 


2.8 Arrays 


The C language has arrays like BASIC. For simple cases (arrays of 
int, short, char or double) the structures used are almost 
identical to those in BASIC. 

Let’s consider the example of determining which numbers are 
produced most frequently by the random number generator. 

To do this we will have an array of twenty integers 0 to 19. We’ll 
generate a random number between 0 and 19. To count the numbers, 
we will increment the array element whose index is the random 
number. For example, if it is 6 we will increment element number 6 of 
the array. When we’ve finished we will know how many times each 
number has been chosen. 

Increment means ‘add one to’. 

Those of you who can read French, may be interested in the following 
from the French version of this manual: 

«Ajouter deux, c’est deuxcrementer, ajouter trois, c’est 
troiscrementer, etc... Ne pas confondre deuxcrementer avec 
decremented qui signifie retrancher un.» 
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i + + ) 


int arrC20U; 
i n t i ; 
m a i n ( ) 


for 

(i 

= 0; i 

< 20; 



a r r C i ] 

= 0; 

for 

( i 

= 0; i< 

: 1 0 0 0 ; 



arrCRan 

d om ( ) 

for 

(i 

= 0; i 

< 20; 



p r i n t f ( 

" %d : 

e vn t 

_k i 

e y b d ( ) ; 



i + + ) 

% 20 ]++; 
i ++ ) 

%d \ n " , i 


a r r C i ] ) ; 






The first line declares an array of 20 elements of type int. It is called 
a r r . 


In BASIC, this corresponds to DIM ARR(20). 

In BASIC, array indices are enclosed in parentheses, in C you use 
square brackets. It’s not our fault! 

In the program we’ll need an integer variable. In a fit of originality it’s 
called i . 

The first statement in the program is a for loop. It initialises all the 
elements of an array to zero. The variable i varies from 0 to 19 (i =0 
and i <20). 


When we declare an array of integers with int a r r C 2 0 ] ; the 
indices vary between 0 and 19. So arrCO] is the first element and 
a r r C 1 9 ] is the last. 


But be careful, there are no checks for array indices. If you want to 
read from or, worse, write to element arrC450] no-one will stop you. 
But 9 times out of 10 the machine will crash. 

Is this stupid? Yes and No. The language is defined this way and it 
can be very useful in certain cases. Be very careful with your array 
indices. 


HiSoft C has an option to test to see if pointers have certain nasty 
values and if so give an error. This may happen if you get your array 
indices wrong or then again it may not. 
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Let’s get back to our program. 

The third statement is another for loop: 

for Ci = 0; i < 1 0 0 0 ; i + + ) 

arrCRandomO % 201++; 

This loop is executed 1000 times. That is to say the statement 
arrCRandomO % 2 0 1 + + is executed 1000 times. So the variable i is 
a loop count that varies between 0 and 999 or 1000 times. 

This statement that is executed 1000 times works as follows: a 
random number is chosen using the Random ( ) function. To make 
this between 0 and 19 we find its remainder when divided by twenty 
using Random ( ) %20. So we’ve got a random number between 0 and 
19. 

This value is used as the index for the element that we want to 
increment. For example if 6 is chosen it will increment element 
number 6 of a r r. Using this we can determine which numbers occur 
most frequently. 

The element of the array we want is called arrCRandom()%201 as 
Random ( )%20 is the index. 

You can wipe your brow now, we’re nearly there! 

We have seen in several exercises that to add one to the variable i , we 
can just write i + + . This is equivalent to i = i + 1 . 

So to add 1 to arr[Random()%201 we just need 

arrCRandomO % 201 + + ; 

That’s it. It doesn’t take long to write but it does a lot. 

The program repeats this statement 1000 times, picking 1000 
random numbers and incrementing the corresponding array 
element. 

When execution of the loop finishes, most of the work of the program 
is done; all we need to do is display the results on the screen. For each 
element of the array, we are going to write its index (between 0 and 
19) and its value (theoretically between 0 and 19). 
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We have a loop whose counter goes from 0 to 19 and uses a p r i n t f 
statement for the screen output: 

for (i = 0; i < 20; i + + ) 

printfC" %d : % d \ n " , i, a r r C i ] ) ; 

We’ve used i yet again as the loop variable, this time varying between 

0 and 19 (i=0 to i<20). 

The p ri n t f function has three parameters. 

The last two numbers represent the two numbers to write: i and 
a r r C i 1 . 

The first parameter gives the format with which the numbers are to 
be written. It’s a string " % d : d \ n " . The first % d replaces the value of 

1 and the second writes the value in a r r C i ] . If, for example, i has 
the value 6 and a r r C i 1 is 52, then the statement: 

printfC" %d : % d \ n " , i, arrCil); 

displays the following : 

6 : 52 

The two characters \ n cause the cursor to move to the start of the 
next line so that the display for each element is on its own line. 


2.9 Conclusion 


We have seen in this section the basics (pardon the pun) of 
programming in the C language. C is a language that needs more 
care than BASIC or Pascal but it is also more powerful. We have seen 
this in the last example. 

You can write things veiy concisely in C. This can make programs 
more difficult to read but can also mean that they run quicker when 
compiled. 

We haven’t seen all the features of C so far; the C that is explained in 
this section corresponds to a modem BASIC. C has many other 
facilities. To summarise, structured types, pointers, 42 arithmetic & 
logical operators, macro pre-processor, modular programs, pointers 
to functions, recursion etc... 

To discover all these, equip yourself with one of the books in the 
bibliography, your HiSoft C disks and a large dose of patience! 
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3.1 Programming with GEM 

f37TTl GEM itself 


3 Introduction to GEM 


This section will describe some of the secrets of GEM that you can 
uncover using the toolbox of functions that will let you open 
windows, use dialog boxes and menus. 





GEM stands for Graphics Environment Manager. GEM lets you 
“manage your environment graphically" via icons and windows, 
letting you open windows, pull down menus move icons etc... 

For the C programmer (that’s you), GEM is available to you via a 
library of functions. 


For example, there’s a function to open a window, and another to 
close it. Another function draws a line between two points, another 
displays text with formatting attributes, and another waits for a 
menu selection. 

GEM has about 200 of these functions altogether. Suitably used they 
let you create programs with windows and pull down menus. All the 
GEM AES and VDI functions are available from HiSoft C, but the 
HiSoft C toolbox has been created to make things easier. 
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3.172 The~HiSoft C toolbox” 


GEM lets vou create windows and pull down menus. However if 
you've tried programming with GEM before, you ve probably realised 
that calling it is arduous to say the least. 

The documentation doesn’t help. The only official documents are 
based on those for the IBM-PC and designed for professional 
programmers (but then you have to be a registered developer to ge 
hold of it!) and doesn’t include a single proper example. Most of the 
other books available are shortened versions of the official ones but 
„ rP i US t as difficult for a beginner to use. There s one thing to be 
thankful for, at least these are written in English (well American 

anyway)! 

Most people find learning to program GEM long and hard work. 
GEM is powerful but huge. For example, to write a program which 
opens a window on the screen and closes it immediately takes about 
forty lines of C. In assembler, it’s even worse and you need about 100 
instructions. 

This is because you need to use lots of functions to program with 
GEM. For this reason, HiSoft C includes a library or toolbox of 
functions that lets you use most of GEM’s facilities but is very muc 
simpler to use. The toolbox means you can use GEM effectively and 
easilv. These function provide a ‘software cushion’ between you and 
GEM. You don’t need to dive into hundreds of pages o 
documentation to work out how to do each little thing. 

We haven’t ignored the purists however. All the standard GEM 
library functions are available with their standard names. If you have 
been through the struggle of learning GEM with another language 
implementation, you can use your hard-earned skills straight away. 
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3.2.1 What is a window? 


You already know what windows are, because you have used the 
GEM Desktop and HiSoft C. A window is a part of the screen with a 
border which you can change using sliders, arrow boxes etc. 

As far as GEM is concerned, a window is nothing more and nothing 
less than a border on the screen. You might think that there is a 
GEM function that would let you move within a window on a virtual 
screen of say 1000 lines and 200 columns and update the display... 
but no. GEM has no concept of virtual screens. 

When you open a screen window, GEM draws the border; that’s all. It 
is up to the programmer to generate the display that appears in that 
window. You have to create your own virtual window and use this to 
generate the window display. 

Now we shall look at the HiSoft C toolbox functions for windows. 




3.2.2 Opening and closing a window. 


The first thing we need to do to open a window is to open it, as you 
probably guessed. The function to do this is called open_wi ndow. 

When you have finished using a window you must close it using 
c L o s e_w i ndow. 






Type in and run the following short program: 

int window_no; 
m a i n C ) 

window_no = open_wi ndow ( 4095, 20, 20, 400, 150, 
" window ", " press a key " ); 
evn t_keybd ( ) ; 
c L ose_wi ndow ( wi ndow_no ) ; 


In the first line, we declare an integer variable called w i n dow_no, then 
we have our usual mainO and { . 




The first statement proper in the program calls the ope n_w indow 
function. This draws the window on the screen and has so many 
parameters that they are on two lines. 
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The evnt_keybd ( ) waits for a key press once the window is opened 
but before the window is closed with close _wi ndow. 


3.2.3 The open_window function 


Let’s look in detail at the open_wi ndow function. It has 7 
parameters. 

The first of these indicates the attributes of the window. For example, 
whether it has a title, sliders, arrows, etc... 

Each attribute has a number associated with it. The following table 
gives a list of the numbers corresponding to the various attributes. 


| base 10 

base 16 

Attribute 

i i 

0x66 i 

Title bar with name 

r o 

i z 

0x002 

Close box 

1 4 

0x004 

Full window 

| 8 

0x008 

Window can be moved 

[“76 

0x010 

information line 

1 32 

0x020 

Change window size 

! 64 

0x040 

Up arrow 

128 

0x080 

Down arrow 

j 256 

0x100 

Vertical slider 

512 

“ 0x200 

Left arrow 

| 1024 

0x400 

Right arrow 

| 2048 

0x800 

Horizontal slider 


If you want your window to have several attributes, you use the sum 
of the numbers corresponding to each attribute. 

For example, if you want a window with a title, two sliders, and a close 
box then the parameter value is 1+2+256+2048 = 2307. 

all the attributes above, so our window will be drawn with all the 
possible ‘gadgets’. 

The next four parameters give the co-ordinates and size of the 
window. They are, in order, the x and y co-ordinates of the top left of 
the window, the width and the height. 

These four values are expressed in pixel co-ordinates. The x co- 
ordinate may be between 0 and 639 (in medium & high resolution) 
and the y co-ordinate may be between 0 and 199 (medium) or 0 and 
399 (high). The origin is the top left of the screen. 
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In the example, our window has a width of 400 pixels and a height of 
150. Its top left comer has co-ordinates (20,20). 

The sixth parameter is the name of the window and it is a string. If 
you don’t want your window to have a title use the empty string " " . 

Our window has the original name "window". 

The final parameter is the text that is displayed in the information 
line just below the title. Again, if you have no information line use a 
null string " " . 

The open_wi ndow function returns an integer. This tells us which 
window we have opened and gives us a handle to use when calling the 
other window routines, so that they know which window to operate 
on. So for example when we want to display text in our window we use 
this handle to say which window to write to. 

This is a similar idea to the file pointers that are used to access files. 
When you open a file you are given a file handle to access it 
subsequently. 

If GEM can’t open the window then the value returned is 0. Your 
program should cope with this error condition. 

So that’s it. When you specify all the parameters, the window 
appears on the screen as if by a miracle. 


L 

C 





3.2.4 The close_window function 


An opened window must always be closed, and you mustn’t close a 
window that hasn’t been opened. It makes sense. The 
c lose_wi ndow function does this job for us: 

c L o s e_w i ndowCwi n d o w_n o ) ; 

It has one parameter which is the integer returned by the 
ope n_w i ndow function. This indicates which window is to be closed 
and is used in the functions that use windows; c lose_wi ndow is no 
exception. 

The c Lose_wi ndow function returns a value indicating the success 
or otherwise of the close operation. If there is a problem, such as an 
attempt to close a window that isn’t open, the value returned is 0; if 
all went well the value returned is not zero. 




GEM Introduction 


HiSoft C 


Page 97 


The returned value is only provided for information. Normally it will 
always succeed. This value is often ignored, as in the example above. 
The calling program simply ‘throws away the value returned. 


3.2.5 Writing in a window 


We have seen that a window is a screen area with a border, no more 
no less. So we need some functions to change the display in the 
window. 

The pri nt_wi ndow function lets us write into a window without 
bothering about the position of the text. The following program, after 
opening the same window as the previous example, writes some text 
inside the window. 

i n t w i n d o w_n o ; 
ma i n C ) 


window_no = op en_wi ndow ( 4095 , 20, 20, 400, 150, 
" window ", " press a key "); 
pri nt_wi ndowCwi ndow_no, "line 1"); 
pri nt_wi ndowCwi ndow_no, "this is line 2"); 
pri nt_wi ndowCwi ndow_no, "this is line 3"); 
evnt_keybd ( ) ; 
c lose__wi ndowCwi ndow_no) ; 


This program is identical to the previous one apart from the three 
calls to pri n t_w i ndow that have been added. Three messages are 
written in the window. 

Run this program to see the effect of this function. 


print _w i n d o w has two arguments. 

The first is the integer handle of the window that is returned by 
ope n_w i ndow. It indicates which window is to be written to. 

The second is the text to display in the window. It is a string of 
characters enclosed in quotes. 

The print ^window function returns a value indicating whether 
there was a problem writing the text in the window. If an error occurs 
then 0 is returned otherwise a non-zero value is passed back to the 
calling function. 


> 


3.2.6 The print_window function 
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In practice, this never fails unless the window handle is wrong or if 
the string is a pointer to an invalid area of memory. Thus this return 
value is often ignored as in the example above. 

This function positions the text itself. The first time you use this 
function, the text is written on the first line of the window. 
Subsequent calls write the text on the following lines. Thus a newline 
is always inserted at the end of each string that is written. If you 
want to write somewhere else, use the pos_wi ndow function, 
p r i n t__w i ndow works in a similar way to PRINT in BASIC. 

If the text is too long to display in the window, the end of the message 
isn’t displayed - it’s clipped to fit in the window. 

If you write too many lines to the window, nothing is shown below 
the bottom of the window and it will not scroll; any subsequent text 
will not be displayed but will be ignored. 


c 


The display is always within the border of the window. 


3.2.7 The pos_window function 


This function lets you change the position where the text written 
with print _wi ndow is displayed. 

The program below writes "hello" at line 5 column 5 and then 
closes the window: 






int window; 
mai n ( ) 

window = open_wi ndow( 2307, 20, 20, 400, 150, 
"title",""); 

pos_wi ndow (wi ndow, 5, 5); 
pri nt_wi ndow (window, "hello"); 
evn t__keybd ( ) ; 
c lose_wi ndow(window); 

> 

The window is opened with a title, both sliders and a close box. The 
values of these attributes are 1, 2, 256 and 2048. Their sum is 2307, 
and this is used as the first parameter of open__window. 

The co-ordinates and size of the window haven’t been changed from 
the previous example. They are (20,20) and (400,150) respectively. 

The window name has changed to "title" and there is no 
information line and so the last parameter is an empty string 




GEM Introduction 


HiSoft C 


Page 99 


The statement 

p o s_w indowtwindow, 5, 5); 

indicates that the next string is to be displayed at line 5 column 5 
within the window that we have opened. 

Then the text is displayed at the position fixed by the pos_wi ndow 
statement. 

Finally, after waiting for a key, we close the window. 

Let’s take a closer look at the pos_wi ndow function. It has three 
parameters. 

The first is the integer that is returned by the open_window 
function. It indicates which window is to be written to. 

The next two parameters indicate where text is to be displayed. They 
are first the column and then the line. Both values are specified in 
characters relative to the top left of the window. Thus they must be 
between 0 and 79 for the column and 0 and 24 for the line. If the 
values used are too large, and the cursor is thus positioned outside 
the window, no text will be displayed by the next print .window call. 
No indication of this error is given. 

If an error is detected then this function returns 0, otherwise a non- 
zero value is returned. This will only happen if the window number is 
wrong and so this is often ignored. 

Note that the pos_window function doesn’t actually display any 
text. It must be used in conjunction with print .window. Text 
specified to print_window appears at the position given by 
p o s_w i ndow. 
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3.2.8 Clearing a window 

There’s a function to clear out the inside of a window. The following 
program opens a window, and writes " h e L L o " into it and waits for a 
key press. It then clears the window contents, displays "Hello, 
world" and waits for another key. Finally the window is closed. 






int window; 
m a i n ( ) 

{ 

window = ope n_w i ndow ( 2307, 20, 20, 400, 150, 

"title",""); 

print _window(window, "hello"); 
evnt_keybd ( ) ; 
c l ea r_w indow(window); 

p r i n t_w i n do w ( w i nd ow , "hello, world"); 
evnt_keybd ( ) ; 
c l os e_w indow(window); 

> 


The function c l e a r_w i n d o w clears out a window. It has one single 
parameter. This is the integer that is returned by the open_wi ndow 
function. It indicates which window is to be cleared. 

The value returned by this function is an error indicator. As usual it 
is 0 if there is an error and non-zero if the operation is successful. 
This value is normally ignored. 


Exercise 13 

Write a program that opens two windows and writes alternately to 
them both. 






3.2.9 The size_window function 

This function lets you find out the size of the available work area 
inside a window. 

In practice, this space is the total space used by the window when 
opened minus the space used by the window’s borders. 


The borders contain the title bar, sliders etc... 

Vw 

u 
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Here’s an example of a program that draws a straight line between 
the opposite comers of its window. 

int x, y , width, height, win; 
m a i n ( ) 
t 

win = ope n_w i ndow ( 2307, 20, 20, 400, 150, 

"title",""); 

si ze_window(win, &x, &y, Swidth, Sheight); 

drawCx, y, x+width, y+height); 
evnt_keybd( ) ; 
c l o s e_w i ndowCwi n); 

> 

The first line of the program declares the integers x , y , width and 
height which will contain the work area of the window. 

The integer w i n is used to store the handle of the window that we are 
using. 

The window is opened by the open_wi ndow function. Then the size of 
the inside of the window is obtained by calling s i z e_w i n d o w. 

The function draws a line between two comers of the window, we wait 
for a key press and then the window is closed. 

Let’s examine the si ze_wi ndow parameters in detail. It has five 
parameters. 

The first is the window handle as returned by the open_wi ndow 
function. This indicates which window to find the size of. 

The four other parameters are going to receive the co-ordinates of the 
area inside the window. These are, in order, the x and y co-ordinates 
of the top left corner, then the width and the height; these 
parameters are modified during the call of the function. They are set 
up to be the work area of the window. 

In this program you should have noted the presence of the & 
operator before the names of these parameters in the function call. 

This & symbol is absolutely essential for the si ze_wi ndow function 
and indicates that the parameters are to be modified by the function 
(see Section 3.2.1 1 for the details of this). 
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3.2.10 The draw function 


The draw function is new. 

It draws a straight line between two points. It has four parameters. 

The first two parameters are the x and y pixel co-ordinates of the 
first point. Their values must be between 0 and 639 for x, and 0 and 
399 or 0 and 199 depending on the resolution for y. 

The other two parameters are the graphics co-ordinates of the other 
end of the line. 

If the co-ordinates are outside the limits given above then only that 
part of the line visible on the screen is drawn. 

This function does not return a value. 


3.2.11 Ways of passing arguments 


A function parameter is only a copy of a variable. Only the value of the 
variable is passed to the function. Thus, modifying a parameter 
within a function does not modify the variable that is used when the 
function is called. We say that the parameter is passed by value. 

However, there is a method so that you can modify variables that are 
passed as parameters. All you have to do is precede them with the & 
operator. 

Then it is the variable itself that is passed and it can be modified. We 
say that this is a variable parameter. 

If you have understood this properly, the hardest part is over, 

Be careful, as in C if a parameter is to be used by value it must be 
called that way. Similarly when using a variable parameter you must 
use the & sign. 

Otherwise 99 out of a 100 times the machine will crash. 

As a general rule, parameters are passed by value. No problem. Every 
so often a function must modify a parameter. Such a parameter 
must always be preceded by a & . 
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Exercise 14 

Write a program which opens a window of a random size. 

Then, inside this window draw a ray of lines in all directions starting 
from one comer of the window. 


3.2.12 Conclusion 


We have seen in this section how to open a window and how to draw 
and print inside it. 

The use of sliders, arrows, and close boxes is described in Section 3.5 
concerning events. 


3.3 Dialog boxes 


3.3.1 What is a dialog box? 


You have already seen dialog boxes. They are a sort of window 
without sliders or title bars that appear in middle of the screen and 
ask you for information. 

For example, when you select Set Preferences from the Desktop, a 
dialog box appears and asks if you want confirmation for copies, 
what screen resolution you want etc. 

Such a box consists of an outer box and various objects such as 
buttons, text, and icons and which can be selected with the mouse or 
changed with the keyboard. 


3.3.2 Creating a dialog box 


There are two stages in using a dialog box in your program. 

First create your box. That is, define its size and its various objects 
(buttons, text, icons etc) that you want to put in it. This is the first 
stage that the user of the program doesn’t see. 

Then you must display the box on the screen and let the operator use 
it. This is the second stage. 

Note that the box creation stage is totally separate from its display 
on the screen. 
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A box is thus created at the start of the program, once and for all, but 
it can be displayed on the screen as many times as you like without 
having to redefine it. 

The creation of a box itself has several stages. First its size and the 
number of elements within it must be defined with the i n i t_box 
function. 

Then, one by one, we add the different objects that we want to appear 
inside this box. 

This is done with the help of the functions: t ext_box (add a string), 
b u 1 1 o n__b o x (add an exit button), gtext_box (add graphics text), 
edi t_b o x (add an editable text field) and color_box (specify the 
colours of the text, background, and border of graphics or editable 
text). 

Now that we have created our box, we can display it and let the user 
modify it. This is achieved with the d raw_box function. 

It only remains to find out what modifications to the state of the 
dialog box the user has made. We use the readstr_box (read a 
string of text) and readbut_box (read the state of a button). 

It is important to note that only the draw_box function has an affect 
that the user can actually see. The creation of the box is invisible. It is 
only when we call this function that anything appears on the screen. 


3.3.3 The init_box function 


This function creates and initialises a dialog box. It’s the function 
that must be called first and specifies the size of the box and the 
number of objects that will be placed inside it. Put simply, an empty 
box is created. This provides the ground work for you to position text 
and buttons. 

This function has three parameters. 

The first two specify the size that you want to give the box. They are, 
in order, the width and height. Both values are expressed in 
characters. They must be between 1 and 24 for the height and 1 and 
80 for the width. 

The third parameter indicates the maximum number of elements 
that you will be allowed to add to this dialog box. 
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For example, if you give this value as 5, you may put up to 5 elements 
in the box. You can thus, for example, use 2 buttons and 2 strings. Or 
equally, 1 button and 4 strings, so long as there aren’t more than 5 
objects. 

This function returns an integer. It is the handle for the box that we 
have just created. This is its number. It lets us distinguish between 
different dialog boxes when we want to use several. 

For example, let’s create a dialog box 20 characters wide by 5 
characters high. Inside it we only want a string of text and an exit 
button, i.e. two objects. The statement to start off the creation of this 
box is: 

box = i ni t_box ( 20, 5 , 2); 

This function doesn’t produce any result on the screen. It is only 
when we have completely defined this box that we can call d raw_box 
and it will appear on the screen. 


A dialog box contains messages to indicate, for example, how to use it. 
These strings of text are positioned in the box using the text_box 
function. 

You must create an empty box using the i ni t_box function before 
calling this function, like all the functions that add objects to a dialog 
box. 

The function text_box has four parameters that let you specify the 
box to which it is to be added, where to position the text, and finally 
the text itself. 

The first parameter is the integer that is returned by i ni t_box. It 
indicates in which box the text dialog is to be positioned. 

The following two parameters let you position the text within the 
dialog box. They are the co-ordinates of the first text character in the 
form column and then line. They are expressed in numbers of 
characters relative to the top left of the dialog box. For example if you 
give both values as 0 then the text appears in the top left of the box. 

The last parameter is the text that is to be placed in the box. It is a 
string of characters enclosed in quotes. 


3.3.4 The text_box function 
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This function returns an integer. It is the number of the object within 
the box. This value can be ignored, except when you need to 
distinguish between objects that you have added to the dialog box. 
This is generally ignored because text is simply displayed on the 
screen rather than being used to exchange information with the 
user. Its state is never tested as it would be if it were a button that the 
user could select. 

This example builds on the example of i ni t_box. We have added two 
t ex t_box statements to add two text strings to the box: 

box = init_box(20, 5, 2); 
text_box (box, 1, 1, "text 1 " ) ; 

t ext_box ( box, 1, 3, "text 2"); 

These three statements don’t make up a valid program because you 
must have a button in a dialog box so you can click on it to exit the 
dialog box. 




3.3.5 The button_box function 


Buttons are used for two purposes in dialog boxes. They let the user 
^ choose between several possibilities using radio buttons. For 
example, when you want to search for a word using the Find 
command of HiSoft C you are presented with a dialog box and you 
can choose the direction of the search by clicking on the appropriate 
button. 












The second use of buttons is to close the dialog box. These are often 
the usual Ok and Cancel buttons. 

The but t on_box function lets us add one of these buttons to a dialog 
box. We can specify its position and its type (radio or exit). 

It has five parameters. The first four are the same as for the 
text_box function. 

The first is the integer that is returned by i ni t_box. This handle 
indicates to which dialog box the button is to be added. 

The next two parameters are the co-ordinates to position the button 
in the box. They are in character co-ordinates (line then column). 

The fourth is the text of the button, as a string of characters in 
quotes. 


w 
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The final parameter is unique to the button_box function. It 
indicates the button’s type. This value is detailed in the reference 
section under button_box. 

There are two types of button. 

Radio (or choice) buttons let the user select one of several possibilities 
without leaving the dialog box. For these this parameter should be 17. 

Exit buttons cause the dialog box to be closed when the user clicks on 
them. If you want to create such a button use 5 for the final 
parameter. 

This function returns an integer; this is the index of the object within 
the dialog box. It is used to distinguish this button from other ones. 

The following examples show some simple uses of the button_box 
function: 


ok = but t on_box ( box_no, 1 , 2, "OK", 5); 

This example creates an exit button (last parameter=5) in the dialog 
box given by box_no. This is placed at line 2 column 1 from the top 
left of the dialog box. It contains the text M 0K M . 

Finally the number of this box is stored in the variable called o k . 

Now for a second example: 

choicel = but ton_box ( box__no, 4, 3, "Choice 1", 17); 

choice2 = but ton_box ( box_.no, 4, 4, "Choice 2", 17); 

choice3 = but ton_box ( box_no, 4, 5, "Choice 3", 17); 

These three statements create three buttons that will let the user 
choose between Choicel, Choice 2 and Choice 3 . The value 1 7 as 
the last parameter means that these are radio buttons. 

The three buttons are inserted in the dialog box given by box_no all 
in column 4 but one beneath another in lines 3, 4 and 5. The text 
inside these buttons is Choice 1, Choice 2 and Choice 3 
respectively. 

These buttons aren’t exit buttons (as the last parameter is 17). When 
you click on one of them it will be selected and appear highlighted, but 
the dialog box isn’t closed. 

When the user clicks, for example, on Choice 1 this will be the only 
button selected. If either of the other two had been selected they will 
return to normal. 
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Then, when the choice has been made, we click on OK to confirm the 
choice and exit the dialog box. 


C 

C 


3.3.6 The draw_box function 


We have seen that this is the function that actually draws a dialog 
box on the screen. 

In general, a box is first created using the three functions that we 
have just discussed. Then it is displayed in its full splendour all at 
once. 

The draw_box function provides this complicated display function. 
The box is drawn on the screen, the mouse cursor appears and the 
user can select the buttons and edit the text that have been drawn in 
the box. 


c 




Then, when the user clicks on an exit button, the box is removed and 
control returns to the calling program. 

Here’s an example so we don’t get out of practice. 

Type in and run the following program: 

i n t box; 
m a i n ( ) 

box = init_box(18, 8, 2); 

bu t t on_box ( box , 6, 6, " OK ", 7); 

t ext_box ( box, 2, 2, "click on OK"); 

d raw_box (box) ; 

> 

Let’s examine this example in detail. 

The first line declares an integer variable called box. This will be used 
to store the number of the box that we are building up. 

The first proper statement initialises the box. It is to be 18 characters 
wide (the first parameter) and 8 characters high (the second 
parameter). 

The box will contain a total of 2 items (third parameter). 
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The statement: 

bu 1 1 on_box ( box, 6, 6, " OK " , 7); 

adds the first of these objects to the box. It is a button with the text 
OK and positioned at column 6 line 6. This is an exit button (last 
parameter is 7). So when this button is clicked on the dialog box will 
be closed. 

The second object is added using: 

text_box(box, 2, 2, "click on OK"); 

This is a string at column 2 line 2 and its text is c l i c k on OK. 

Finally the statement: 

d ra w__box ( box ) ; 

draws the box on the screen and waits for the user to click on OK. 

The d ra w_b o x function returns an integer result representing 
which button caused the box to be exited. This is the number of the 
box as returned by button_box when the button was created. You 
need to know which exit button was pressed if there is more than one 
exit button. 

This value is ignored in the above example because there is only one 
exit button; it must be this one that caused the box to be closed, so 
the program can safely ignore this information. 


3.3.7 The readbut_box function and radio 
buttons 


There are two types of buttons. 

We have already seen that these are exit buttons, which cause the 
dialog box to be closed and radio buttons, that let the user choose 
between several options. 

For buttons in the latter category we need to know which button the 
user has chosen. The draw_box function returns which exit button 
the user clicked on but not the last exit button that was pressed. 

To do this there is the readbut_box function. It tells us if a button is 
selected or not. 
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In the following example a dialog box is displayed on the screen and 
the user is given a choice. She or he must click on a button 
corresponding to their age. Finally the user must close the box by 
clicking on OK. 

int box; 

int agel, age2, age3; 
mai n ( ) 

box = i ni t_box ( 30, 10, 5); 
bu t t on_box ( box, 12, 8, " OK ", 7); 
t ext__box (box, 4, 2, "Select your age..."); 
agel = but ton_box C box, 1, 5, " 00-20 ", 17); 

age2 = but ton_box ( box, 11, 5, " 21-40 ", 17); 
age3 = but ton_box ( box, 21, 5, " 41-99 ", 17); 

d raw_box C box ) ; 

if ( readbut_box (box, agel) == 1) 
printfC "Youngster. . . \ n " ) ; 
if C readbu t_box C box, age2) == 1) 

printfC" In the prime of your life\n"); 
if C readbut__box C box, age3) == 1) 
printfC "Ancient. . .\n"); 
pri ntf C "press a key\n"); 
evn t__keybd C ) ; 

> 

The variable box contains the dialog box number . The integers agel, 
a g e 2 and a g e 3 are where the numbers of the three buttons 
containing age ranges are stored. 

The first real statement initialises the box to have a width of 30 
characters and a height of 10 characters. Inside the box we can 
insert 5 objects which in this case will be, a string, an exit button and 
three radio buttons. 

In line 8 at column 12 we position the OK exit button, thus, 

but t on_box C box, 12, 8, " OK ", 7); 

The value 7 as the last parameter means that this is a default exit 
button. This is the button that will be selected if we type Return. 

Next the string Select your age is added at column 4 line 2. 

t e x t__b o x C b o x , 4, 2, "Select your age... ); 
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The statement 

agel = but ton_box ( box, 1, 5, " 00-20 ", 17); 

positions the first of the three radio buttons in the box. It represents 
the choice of 0 to 20 years. The last parameter is 17 because this is a 
radio button. 

The index of this button is stored in the variable agel. 

The two statements: 

age2 = button_box(box, 11, 5, " 21-40 ", 17); 
age3 = button_box(box, 21, 5, " 41-99 ", 17); 

position the other two radio buttons next to the first at columns 1 1 
and 2 1 where the first one was in column 1 . 

The three numbers of the radio buttons are stored in the three 
variables agel (0-20), age 2 (21-40) and age 3 (41-99). 

Next the box is drawn on the screen using the call to the d raw_box 
function. The user must select one of the three ages and then press 
on the OK button. 

The program must now work out which of the three buttons has 
been selected with the help of the readbut_box function. This tells 
us if a radio button has been selected or not and has two parameters. 

The first is the number of the dialog box in which the button is 
located. This is the integer that was returned when the box was 
created with i n i t_b o x . 

The second parameter is the number of the radio button whose state 
we are finding, within the box. This is the value returned by 
button_box when the radio button was created. 

The function returns a value, the state of the box. If this value is 0 
then the button is not selected. If however the result is 1 then the 
button is selected. It’s that simple. 

Back to our example. The statement: 

if ( readbut_box C box, agel) == 1) 
printfC Youngster. . .\n"); 

tests if the button 0-2 0 whose number is stored in the agel variable 
is selected. If it is then the value returned by readbut_box will be 1 
and the p r i n t f statement is executed. 
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In the same way the next two statements test the other two radio 
buttons. 

Note that only one radio button is ever selected. If the user tries to 
select another one, the original one is de-selected. 

The readbut_box function should only be called after a draw_box 
statement where a dialog box will have been displayed and the user 
has selected a button. This button should always be a radio button 
that has been created using button_box. 


3.3.8 The edit_box function and editable fields 


The dialog boxes we have created so far let you click on buttons as 
much as you like, but they don’t let you enter text using the 
keyboard. For example, when you create a new folder on a disk the 
Desktop will display a dialog box and ask you to type the name of the 
folder. 

The edi t_box function lets you create such items so that you can 
enter text. 

For example the following program asks the user to enter the current 
date : 

i n t box; 
i n t edit; 
char * d a t e ; 
mai n ( ) 

box = i ni t__box( 33, 7, 3); 
but ton_box ( box, 14, 5, " OK ", 7); 
text_box(box, 1, 1, "Enter to-day's date---"); 
edit = edi t_box(box, 11, 3, "250687", 

"999999", 3); 

d raw_box ( box ) ; /* draw the box */ 

date = readst r_box (box, edit); /* read the date */ 
puts(date); / * write the date on the screen * / 
evn t_keybd ( ) ; 

> 

This program starts in a way with which you are familiar. A dialog 
box is created and an exit button called 0 K and a text string Enter 
to-day ' s da t e is added to it. 

To change the standard recipe, we have added a new call to add a bit 
of spice. This is the edi t_box function and it has seven parameters. 
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Ok, let’s start at the beginning. 

The first three parameters we have seen before. They are the dialog 
box number, the column and line where the text will be displayed. 

An editable field (where we can enter text) has three parts. 

First there is the template (or site) of the field. It is where the text is 
physically written. In general it uses the underline characters: 
” These characters are replaced by the data that we want to 

write. This is the fifth parameter to e d i t_b o x . 

In our example the string consists of" / / This lets us type six 

characters with slashes between each pair. 

Thus, we need to know the maximum size of text in advance. 

Next there are the characters that we are allowed to enter, or 
validation string. We can just accept digits or only upper case letters 
for example. 

For each character that we can enter, we must specify which 
characters are allowed. To do this, each character in the template 
field has another character associated with it. This is represented by 
a string of characters indicating which characters are valid. 

In this example, this string is "999999", meaning that only digits 
are allowed. No other character may be typed. There are many other 
possibilities however. For example, using just the character '* A " , 
upper case letters only are allowed. 

Here’s the full selection: 


9 

Only 0-9 

A 

A-Z and space 

a 

A-Z, a-z, 128-255 and space 

F 

A-Z, a-z, 0-9, 128-255, : ? * _ 

f 

A-Z, a-z, 0-9, 128-255, _ 

N 

A-Z, O'- 9 and space 

n 

A-Z, a-z, 0-9, 128-255 and space 

P 

A-Z, a-z, 0-9, 128-255, \ : ? * . _ 

P 

A-Z, a-z, 0-9, 128-255, \ : _ 

X 

all characters allowed 
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In the above A-Z includes non-English capital letters. 128-255 
means that all characters with value greater than 128 can be used 
including lower case non-English letters and the £ sign. Note that 
the f validation character is not normally documented but is present 
in all versions of the operating system that we have used. 

We could replace the " 9 9 9 9 9 9 " in our example with " X X X X X X " . Then 
the user could type any character on the keyboard not just digits. 

Finally, the third part of an editable text field is the text that will be 
displayed for the user to modify if he wishes. This is the fourth 
parameter in the edi t__box function call. In the example this will 
write 2 5 0 6 8 7. This is combined with the template (the fifth 
parameter) to produce the display 25/06/87. When you run the 
program, it won’t be that date so you will need to delete it (using the 
Esc or Backspace keys) and enter the new one. 

We could replace the " 250687" in the function call with " " . This 
would make the field empty when the dialog box is displayed 

producing " / / ”, and you wouldn’t have to delete the old date 

before entering the new one. 

An editable field may, or may not have a border round it. The last 
parameter of the function specifies the border. 0 means no border, 1 
to 3 mean borders of increasing thickness. If this parameter is not 
between 0 and 3 no border is drawn. 

This function returns the index of the edit field within the dialog box. 

So at last, we have finished with the edi t_box function. 

Next in our example, the draw__box function is called to display the 
box and let the user enter the date. 


3.3.9 The readstr_box function 


This function is used to read text that has been entered using an 
editable field. In our example we want to find the date that has been 
entered by the user. 

To do this we use the readstr_box function which is much simpler 
than edi t_box, it only has two parameters. 

The first is the number of the dialog box, where the text that we want 
to read is placed and the second is the number of the editable field 
within that box. This is the value returned by edi t_box when the 
item was created. 
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As if by magic, the value returned is the string of characters that was 
typed; in our example the date. 

For C experts, the type of the value returned is char*, that is pointer 
to character. It’s the address where the characters typed were 
stored. 

In our example we have a call to puts to display the string containing 
the date on the screen. 


3.3.10 Graphics Text 


It is possible to have text with graphics attributes in dialog box. 

So far we have just had boring strings, but they may have different 
colours, border, fill patterns and even different sized characters. 

int box; 
int text; 
ma i n( ) 

box = i ni t_box ( 20, 10, 3); 

button_box(box, 6, 8, " OK ", 7); 

t ext_box ( box, 3, 2, "click on OK"); 

text = gtext_box(box, 1,5, "graphics text ", 1 , 2, 1 ) ; 

color_box(box, text, 0, 2, 3); 

draw_box(box); 

> 

This example displays a string in small characters, with a black 
border, red characters (on a colour screen!) and on a green 
background. 

You will remember the usual box creation function (20 characters 
wide, 10 high, containing 3 objects). A button and a string are added 
to the box with text of 0 K and click on OK. 

Then a couple of new functions gtext_box (to create graphics text) 
and color_box (to change the colour of the text). The box is then 
displayed using draw_box as ever. 
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3.3.11 The gtext_box function 


This function places a graphics text item in a dialog box. This is 
similar to a text_box but the text can have several effects applied to 
it to relieve the boredom. 

This function has seven parameters. The first is the number of the 
dialog box to which the text will be added. It is always the first 
parameter in all the object addition functions. 

The next two parameters give the position of the text within the box 
as in the t e x t _b o x function for example. 

The fourth parameter, if weve counted right, is the string of 
characters that are the actual message text of the box. 

So far this has been exactly the same as the text_box function. But 
this changes with the next parameter which is the size of the 
characters. If this is 0 then they are written as normal, otherwise 
they are written as small text. 

The parameter before the last one is for the border of the text box, 
with 0 meaning no border, 3 a very wide one and 1 and 2 meaning 
borders in between. 

The background on which the text is written can have the ‘darkness’ 
of the fill specified. This is a value between 0 (white) and 7 (full black) 
with values from 1 to 6 being shades of grey. 

You may need to use the co L o r__box function so you can read your 
text! 

The gtex t__bo x returns an integer, which is the index of the object 
within its box as ever. In general this value is ignored as the text is 
simply displayed on the screen rather than being used in interaction 
with the user. However there is one time when you need this value 
and that is when calling c o L o r_ b o x . 


3.3.12 The color_box function 


As we have already said this function is used to set the colours of 
graphics text. It has five arguments. 

The first is the number of the dialog box in which the graphics text 
has been added. The second is the index of the text within that box. 
This is the value returned by the gtext_box function. 
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The last three parameters indicate the colours of the border, the 
characters and the background. 

With a monochrome screen only the values 0 and 1 should be used, 
corresponding to white and black respectively. 

If you are using a colour screen in medium resolution 4 values are 
allowed: 


6 

white 

l 

black 

* 2 

red 

3 

green 


For example, if you want a black border, red characters and green 
background, specify these parameters as 1, 2 and 3. 

If you don’t like these colours they can be changed with the Control 
Panel or using the GEMVDI v s_c o l o r function. 

Note that if you want a non-white background you will need to 
specify a non -zero fill pattern in your call to gtext_box. 

Be careful, you can change the colour of text created with edi t_box 
or gtext_box only. You can not do this for buttons (button_box) or 
non-graphics text (text_box). 
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3.4 Menus 


3.4.1 What is a menu? 


You’ve used pull down menus. There is a bar at the top of the screen 
with titles which have menus on them which drop down when you 
move the mouse over them. 

Using the HiSoft C toolbox, this is done as follows: 

int title, elem; 
mai n ( ) 

ini t_menu ( " Desk ", " About Menu", 2, 5); 
ti t le_menu(" File "); 

item__menu(" Load File"); 
item_menu(" Save File"); 
item_menu(" Quit"); 
title_menu(" Options "); 

item_menu(" Search"); 
item_menu(" Replace"); 
d r a w_m e n u ( ) ; 

event (&ti t le, Selem, 0, 0, 0, 0); 

> 

This program creates a menu with three titles: Desk, File and Options. 
In the File menu there are three entries and in the Options menu 
there are two. 

The menu is drawn on the screen (using the draw_menu function), 
then the user selects an item from the menu (using the event 
function) before the menu disappears. 

The event function is detailed in the section on events (See Section 
3.5). This is a HiSoft C toolbox routine; it manages the mouse and lets 
you pull down menus when the mouse reaches the menu bar. It 
returns control to the program when a menu item is selected. 

It is important to note that the ini t_menu, t i t l e_m e n u and 
i t e m__m e n u items create the menu in a way that is invisible to the 
user. Nothing changes on the screen. Only during the call to the 
d r a w_m e n u function does the menu bar appear. The menus can’t be 
pulled down until the event call. 
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3.4.2 The init_menu function 

This lets you initialise and reserve space in memory for a menu that 
you wish to create. It is the function that must be called first during 
creation of a menu. 

i ni t_menu has five parameters. 

The first is a string of characters representing the title of the first 
menu. This is nearly always Desk but you can change it if you like. 
This isn’t the only choice you have... 

The second argument is another string of characters. It’s the first 
item on the Desk menu and is normally used to display an ‘About’ 
box for the program describing the program, its author etc. This 
string must not be more than twenty characters long. In the 
example, we’ve used "About Menu". 

The next parameter is the number of titles of our own that we wish to 
have without containing the Desk menu. 

So in our example this parameter has the value 2. 

For the HiSoft C editor, with the titles File, Find, Run, Move, Block, 
Help and Info, there are 7 titles. To create such a menu this 
parameter must have the value 7. 

Note that this value is the maximum number of titles that you wish 
to include in the menu bar. You can indicate that you want more titles 
than you actually add to your menu. 

Finally, the last argument indicates the maximum number of menu 
entries, not counting the Desk menu items nor the menu titles. 

For example, in the HiSoft C menu there are 63 entries. In the 
program above, there are 5. 

The init_menu function returns an integer. This is the index of the 
‘About’ box in the Desk menu. This number is used to see whether it 
was the item that was selected. (See Section 3.5 on events). 
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13.4.3 The title_menu function 


After intialising a menu with i ni t_menu, we can start to add the 
titles in the menu bar after the Desk menu. This piece of magic is 
performed with the help of the t i t L e_m enu function. 

The new T title is added to the right of the Desk menu if there aren’t 
any other titles. If you have already called t i 1 1 e__m enu then the new 
title will appear to the left of the existing ones. 

The title bar may not contain more than 80 characters. 

t i t L e_m enu only has one parameter. It is the string of characters 
that you wish to add to the menu bar. So in our example it is " File 
" or " Options". 

A value is returned by this function. It is the integer that identifies 
the title that we have added to the menu bar. We need this to find out 
from which menu the user has selected an item. See Section 3.5 
Events. 


;3.4.4 The item_menu function 

This function creates an entry beneath a menu. This item is added 
below the last title that was added to the menu bar. 

This function must not be called before using title_menu. 
t i 1 1 e_m e n u is used to create a title and then item_menu is used to 
add the entries beneath that menu. 

The value returned by this function is the integer that identifies the 
item that we have added to the menu bar. We need this to find out 
which item the user has selected. See Section 3.5 Events. 


3.4.5 The draw.menu and delete_menu 

functions 


These two functions display or remove the menu bar. 

The function draw_menu must be called after the menu has been 
created (using the i ni t_menu, titl e__m enu and i tem_menu 
functions) and before the user can interact with the menu (using the 

event function). 
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If you forget this function, no menu events can occur and the event 
function can wait for ever for a menu event that will never happen. 

Quickly turn to Section 3.5 on events if the event concept isn’t 
crystal clear. 

Neither of these functions have any parameters and both return an 
integer indicating whether an error occurred. This is an integer with 
value 1 (or true) if all went well or 0 (or false) if an error occurs. 

Generally this value is ignored by the program, assuming 
(hopefully!) that all went well. 


3.4.6 The enable_menu, check_menu, & 
$elect_menu functions 


We’ve grouped these three functions as they are all used when 
changing the state of a menu. We won’t give an example here because 
it would need to build on the other menu functions and so be rather 
long. There is an extended example in the examples folder of master 
disk 2 called event.c. 

chec k_m e n u makes a tick (or check mark) appear or disappear in 
front of a menu item. If the item isn’t already ticked the tick appears; 
if it is ticked it will disappear. 

enab L e_menu ‘greys’ an item in a menu. That is, it makes the item 
appear grey so the user may not select it with the mouse. If the item 
is already grey it appears as normal and so is enabled once more, 
hence the name of the function. 

Finally, select _menu makes a title appear in inverse (black on 
white) or if it is already selected in this way it returns to normal. The 
most common use for this is to restore menu titles to normal after 
an item has been selected. 

These three functions all have one parameter and it is used for the 
same purpose in all of them. 

This parameter indicates which item is to be selected, greyed or 
ticked. This is the value returned by the i t e m_m enu or titL e_m e n u 
function. 

All three functions return an integer. This indicates the new state of 
the item. If the item is now selected, disabled or ticked 1 is returned; if 
not 0 is returned. If you try to change the state of an item that does 
not exist then 0 is returned. 
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The select_menu function may only be used with titles; tiying this 
with menu items will always return 0. 

select _menu has a rather special purpose. When you select a menu 
with the mouse the title appears in inverse and remains that way 
until you call select _menu with the number of the title as its 
argument. You can see this in the paleochrome program. 

Here is a tiny program fragment that ticks a menu entiy. 

i n t i t e m ; 

item = ite m_m enu(" menu item"); 
c h e c k_menu (item); 


3.5 Events 

This is the section whose importance we stressed a few pages back. 


3.5.1 What is an event ? 


Events sire the fundamental items in a true GEM program. 

They are single user actions as far as GEM is concerned. This might 
be a key press, a mouse button press, the selection of a menu item or 
the manipulation of a window (moving it, changing the size, clicking 
on an arrow or slider etc). 

An event is therefore GEM’s way of telling you what the user has just 
done with the mouse or keyboard. 

A program running under GEM with pull-down menus and windows 
is based around this concept. Some mis-guided programmers try to 
avoid this, but this is a waste of time; it is much better to do things 
GEM’s way rather than fighting it! 


3.5.2 The layout of a GEM application 

The event function is by far the most powerful and important GEM 
function. GEM applications are built round this function. 

It lets us wait for the user to complete one of the actions described 
below. 

So thanks to this function you can ask GEM to wait for a key press 
and/or mouse click, and/or select a menu, and/or change a window. 
It’s powerful isn’t it? 
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When you make the call you specify which events you want to wait 
for. The function returns to the main program when one of the 
specified events has occurred. 

For example, you can wait until the user selects a menu or presses a 
key. You call the event function ‘saying’ that you want to wait for a 
menu or keyboard event. As if by magic, the function doesn’t return 
until the user has chosen a menu item or pressed a key. 

You will be told whether a key was pressed or that a menu item was 
selected. 

Typically, a GEM application uses events in the following way: 

create the menu 
create the dialog boxes 
open the windows 

While we haven’t finished do the following: 
wait for an event 

Depending on the type of the event 
If it is a mouse event: 

deal with the mouse event 
If it is a keyboard event 

deal with the keyboard event 
If it is a menu event 

deal with the menu event 
If it is a window event: 

deal with the window event 
Close the window 
Remove the menu 


If we translate this algorithm into C, we get: 


i n t 

menu_ 

title, menu_ 

item; 

/* menu item 

selected */ 

i n t 

x, y; 


/* 

mouse co-ord 

i n a t e s * / 

i n t 

event 

—type; 

/* 

event type 


(keyboard 

, mouse . . ) */ 




i nt 

ch; 


/* 

character typed on keyboard */ 

shor 

' t win 

d o w Z 6 1 ; 

/* 

window event 

detai Is*/ 

i n t 

not f i 

n i s h e d ; 

/* 

indicates if 

the program */ 




/* 

has finished 

or not */ 


ma i n ( ) 
t 

c r e a t e__m enu(); 
c r e a t e_d ialogO; 
openwi ndows ( ) ; 
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c 








whi le 
i 


> 


(notfinished) 

event_type = e ven t ( &menu_t i t l e , &menu_item, 
window,&ch, &x, &y); 

if (event_type == 2) /* mouse button */ 

d o_m ouse(x, y); 

if (event_type == 3) /* menu selected */ 

d o_m e n u ( m e n u_t itle, menu_ item); 

if (event__type == 1) /* key pressed */ 

d o_k e y ( c h ) ; 

if (event_type == 4) /* window changed */ 

do__wi ndow (window); 


d e s t r o y_m enu(); 
c l osewi ndows ( ) ; 

> 

Let’s look at this in detail. 


The variables declared at the start of the program are used to store 
the type of event and details about a particular event. They are 
modified by the call to the event function. 

Thus the integers, menu_ti t le and menu_i tern contain the indices 
of the title and item of the selected menu if a menu event occurs. 


The x and y variables contain the position of the mouse if the user 
clicks on a mouse button. 

c h will contain the key that was pressed on the keyboard if a 
keyboard event has occurred. 

The array window contains extra information about a window event. 
For example that a slider has been moved or that the window size has 
been changed. 

even t_t y p e contains the type of event that has just happened. This 
may be a menu, keyboard, mouse or window event. 

The integer notfinished is used to indicate when the program has 
terminated. If, for example, the user clicks on a close box or selects 
Quit from the menu we would set this variable to 0 (false). 

The first three statements in the program initialise the environment 
by calling the functions which open windows, and create menus and 
dialog boxes. We won’t go into detail about these here. 

Then we have awhile loop which waits for and deals with events 
until the user decides to exit the program. 
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Now for the big moment - the event function is called. 

This waits for a keyboard, mouse or window event. See the detailed 
description of the function in the next section. 

We then test which type of event occurred and, depending on the 
event type, we call a specific function. 

Then when the program terminates we call routines to close the 
windows and remove the menu. 

Obviously this program is only a skeleton; it calls functions that we 
haven’t described but which perform specific actions. However, this 
example shows the layout of a GEM program that uses the HiSoft C 
GEM toolbox. 

On your HiSoft C disk, there are two programs showing the handling 
of events called paleochr.c and event.c. 

The commenting of these is un-even but you are likely to find them 
very useful in understanding this complex mechanism. 


3.5.3 The event function 


We will now describe in detail the HiSoft C toolbox event function. 

This function has 6 parameters whose syntax is as follows: 

i n t menu_t i t l e; 
int menu_item; 
i n t k e y_p ress; 
int c L i c k x ; 
int clicky; 
short window H 6 □ ; 
int event_type; 

event_type = even t C &menu__t i t L e, &menu_item, 

window, &key__press, Sclickx, Sclicky); 

Note that the parameters are modified by the call to the function. 
This is the reason for the & character before the parameters. If you 
omit one of these your program won’t work and may even crash. 

In general, these parameters let you indicate the type of events that 
you wish to wait for and, in addition, the details of the event that 
occurred are returned therein. 
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This function has one or two parameters for each type of event. If a 
parameter corresponding to an event is zero, this indicates that you 
do not wish to wait for this type of event. Otherwise this parameter 
must be a variable and when the function returns the variable will 
return the details of that event. 

This function returns a whole number which indicates which event 
has happened. So by examining this variable you can find out if a 
keyboard event or a menu event has occurred. 


Value 

Event type 

| 1 key press 


mouse button click 

3 

menu selected 

[4 

window manipulated 


GEM also has other types of events which are not used as 
frequently, like timer events, which wait for a certain amount of time 
to pass and events that wait for the mouse to leave an area. 

You can not use the event function to access these events; you must 
use the GEM functions e vn t_mu L t i , evn t_t imer or evnt_m o u s e 
directly rather than a toolbox function. 


3.5.4 Menu events 


First of all, what is a menu event? 

When you decide to wait for a menu event, you call the event 
function. The mouse cursor will appear on the screen and the user 
may ‘pull-down’ the menus and select an entry. At the precise 
moment that the mouse button is released the menu event is 
considered over. The event function returns to the calling program 
indicating which menu item has been selected. 

The first two parameters of the event function are concerned with 
pull down menus. If you don’t want to wait for events caused by 
menu selection then these two values must be zero. In place of 
&menu_t i t L e and &menu_i t em, you put the value 0. 

Otherwise, the event function returns the numbers of the title and 
item of the menu entry that was selected with the mouse. 
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Remember that these numbers are identical to the values returned 
by the title_menu and item_menu toolbox functions when you 
create the menu. These two functions give unique numbers 
specifying the menu item. The same values are returned in the 
men u_t i t Le and menuj tern items to inform you which item has 
been selected and the title of the sub-menu. 

For example, if you select the Quit entry from the File menu the 
variable menu_ti t le will contain the number of the title File and 
menu_i tern will return the number for Quit. These values are the 
same as those returned by ti t le_menu and i tem_menu when the 
menu was created. 


3.5.5 Window events 


This event is the most difficult to handle as there are many different 
‘flavours’ of window event: changing the size, closing the window, 
moving a slider etc. . . 

The third parameter of the event function is concerned with events 
applied to windows. Remember that window events occur when the 
user changes the window in any way. For example, clicking on the full 
box, moving the window, or even clicking on an arrow etc. 

When such an event occurs the event function needs to return the 
sort of event (changing the size, dragging a slider) and also extra 
details of that event, for example, when the window size is changed 
the new size of the window that the user has asked for. 

The place where the details of the event are stored must be big 
enough. To do this, an array of six short integers is used. The third 
parameter of event is the name of this array. 

When the function returns, the array contains the full details of the 
window event. 

If you haven’t opened a window, or you don’t wish to deal with events 
that can happen to your window then pass zero instead of the array 
name. 

The full list of GEM window events is as follows: 

• Clicking in the close box 

• Clicking in the full box 

• Clicking on the arrows 

• Moving a slider 

• Changing the size of a window 

• Moving a window without changing the size 
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• Re-displaying the inside of a window 

• Making a window the top one 

The first (number 0) element of the array indicates which event has 
taken place. The significance of the other elements depends on the 
type of event; all the elements are never used at once. 

There now follows a list of all the different GEM window messages 
together with a description of the elements that are used: 

• Clicking in the close box 

element 0: 22 

element 1 : the number of the window to be closed. 

When the user clicks on the close box, the first element of the array 
has the value 22 and the second element indicates which window has 
been clicked on. 

• Clicking in the full box. 

element 0 23 

element 1 the number of the window to make full size. 

• Clicking on the arrows or in the grey part of the slider. 

If the user clicks on a window’s arrows this moves the window 
upwards, downwards, to the right or to the left by one line/character. 
If you click in the grey area of the slider the window should move by a 
page in the corresponding direction. 

element 0 : 24 

element 1 : window number 


element 2 : action to perform: 


6 

page up 


1 

page down 


2 

row up 


3 

row down 


4 



5 

page right 


6 

column left 


7 

column right 



For example, if element 2 contains the value 3, the user has clicked on 
the down arrow of the window. 
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In this case the program should scroll the window one line towards 
the bottom of the file. 


• Moving the horizontal slider 

GEM returns the new position of the slider as a value between 0 (the 
leftmost position) and 1000 (the rightmost). 

element 0: 25 

element 1 : window number 

element 2 : slider position between 0 and 1000. 

• Moving the vertical slider 

GEM returns the new position of the slider as a value between 0 (the 
top position) and 1000 (the bottom). 


element 0 : 
element 1 : 
element 2 : 


26 

window number 

slider position between 0 and 1000. 


• Changing the size of a window 


GEM returns the new size of the window. 


element 0 : 

27 


element 1 : 

window number 


element 2 : 

x co-ordinate of the top right of the 
(should remain unchanged) 

window 

element 3 : 

y co-ordinate of the top right of the 
(should remain unchanged) 

window 

element 4 : 

the new width of the window 


element 5 : 

the new height of the window. 
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• Moving a window without changing the size 

The user has moved the window by dragging on the title bar. GEM 
returns the new window position that the user wants. 


element 0 : 
element 1 : 
element 2 : 
element 3 : 
element 4 : 
element 5 : 


28 

window number 

new x co-ordinate of the top right of the window 
new y co-ordinate of the top right of the window 
the width of the window (unchanged) 
the new height of the window (unchanged). 


• Making a window the top one 


The user has clicked on a window to make it the front one. 


element 0 : 2 1 or 29 

element 1 : number of the window to become active. 

• Re-displaying the inside of a window 

This event occurs when a window is opened, or when it becomes 
larger or when an object (another window or dialog box) has deleted 
the interior of the window. 

element 0 : 20 

element 1 : number of the window to redraw. 

Note : The toolbox function draw_box which displays a dialog box on 
the screen saves the screen before drawing it and restores it 
afterwards. If there is only one window on the screen and it cannot 
change size this event can be ignored. 

Obviously this list will give you something to think about. “Well, have 
I got to cope with all these types if I’m going to use windows ?” I am 
afraid so. However to help you, at least a bit, there’s an example on 
the HiSoft C disks called event . c. It will get you started. 

This concludes our discussion of by far the most complicated event 
type. 
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3.5.6 Keyboard events | 

The fourth parameter of the event function is concerned with 
keyboard events. Such events are simply keystrokes from the 
keyboard. 

When you wait for a keyboard event, you are waiting for the user to 
press a key but it is a bit more serious than saying tt Oi you, I’m 
waiting for a keyboard event!”. 

If you aren’t interested in what the user types you can use zero as 
the fourth parameter. So if you put 0 instead of &key_ press, 
keyboard events will be ignored. 

Otherwise the event function will return a code for the key you have 
pressed in the key_press variable. The low order byte of this is the 
ASCII code of the key; the higher order bytes are special keyboard 
codes that GEM uses all the time. This lets you detect Help keys, A 1 1 
combinations etc. 

If you don’t understand how to use the powerful/obscure facility, 
don’t woriy; you can use the C expression key_press % 25 6 to 

return the normal ASCII code of the key pressed where key_press 
is the variable that you passed to the event function. Obviously in 
this case you can’t check for keys with no ASCII equivalent like Undo 
or the function keys. 


3.5.7 Mouse events 


A mouse event (also known as a button event in GEM-speak) is a click 
on a mouse button. With the help of the event function, you can wait 
for the user to click on the mouse. 

The fifth and sixth parameters of the event function are concerned 
with mouse events. As usual, if you don’t want to wait for this event 
then both parameters should be 0. Instead of & c L i c k x and & c L i c k y , 
put the value 0. Otherwise the event function returns the position of 
the mouse at the moment of the mouse click. 

The examples below show how to call event for a few very simple 
cases. The example programs paleochr.c and event.c show how 
to handle all the types of event at once. 
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i n t men u_t i 1 1 e ; 
int menu_item; 
i n t k e y__p ress; 
int c l i ckx; 
int clicky; 
short window[6]; 
int event_type; 





ma i n 

event_type = eventCO, 0, 0, &key_press, Sclickx, Sclicky); 
/* wait for a key press or a mouse click */ 

event_type = event (&menu_ti t le, &menu_item, 0, 0, 0, 0); 

/* wait for a menu to be selected */ 


event_t ype 
Sclicky); 

/* wait for 
> 


= eventCO, 0, 
a key press. 


window, &key_press, Sclickx, 
mouse click or window action */ 







3.6 Conclusion 


This section has shown how to use GEM via the HiSoft C toolbox 
facilities. Clearly, you can access the standard GEM AES and GEM 
VDI functions directly. These functions are not described here. See 
the books in the Bibliography that document these. 

The toolbox functions which have simplified life for us, are 
themselves written in C; we supply their source in the COMPILE 
folder. 

Have fun reading them, and you will probably soon be happy that we 
have written them for you! 






GEM Introduction 


HiSoft C 


Page 133 


Page 134 


HiSoft C 


GEM Introduction 


4 HiSoft C Library 
Functions 


This section describes all 460 functions in the HiSoft C library. 

We start with a one line summary of each function in the libraries to 
make it easy to find which function you need and then describe each 
function in alphabetic order. 

Some of the functions are specific to the HiSoft C interpreter and we 
supply the source code to these free so that you can compile 
programs that use them. These functions are marked as HiSoft C in 
the reference section. 

The GEMDOS library is used to access the lower levels of the ST 
operating system. 

The GEM AES and GEM VDI libraries are used to access the 
appropriate higher levels of the ST operating system. 

The UNIX library contains the low-level routines that are derived 
from the standard UNIX libraries as used with most 
implementations of C. We have had to make some changes to these 
because of differences in the underlying operating systems. To make 
them all exactly the same the ST would need to be running UNIX of 
course.The differences between the HiSoft C and the UNIX functions 
are described under the particular function. 

Finally, there is the ANSI library. This contains many of the 
functions described in the draft ANSI standard for C and which have 
been implemented under UNIX and in many of the more recent C 
implementations. In particular it is a good idea to use the ANSI file 
handling functions rather than the lower-level UNIX ones as the 
ANSI functions are much more portable. 

If you have used Lattice C 3 you will be familar with these functions 
apart from the HiSoft C ones. Of course. Lattice C 5 also includes 
most of these . 

Other compilers may have additional functions, or they may omit 
some of them. 

Each function is described in the same way. Its name and the libraiy 
that it comes from are given in the heading. 
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Then the syntax and types of parameters are described followed by 
the usage of the function. 

Finally, there may be some other sections, prefaced with an icon: 


This icon is used to indicate a tricky point about a function or 
a common error that beginners make. 

A This is used to indicate a particular usage of a function or a 
trick that may not be obvious. 




This icon is used before an actual example of the use of a 


function. 

A This icon is used to make references to other functions, other 
parts of the manual or the name of a keyword used by the Help 
system. 


4.1 Library Summary 


4.1.1 

The HISoft C library 

Debug control functions 

trac e_o n 

sets trace mode 

trac e__o f f 

disables trace mode 

v a r__o n 

enables display of variables 

v a r_o f f 

disables display of variables 

stop 

stops execution of program 

Dialog Box 

functions 

i n i t_b o x 

creates a dialog box 

d r a w__b o x 

displays a dialog box 

t e x t_b o x 

adds a string to a dialog box 

but ton_box 

adds a button to a dialog box 

gtex t_box 

adds graphics text to a dialog box 

e d i t__b o x 

adds an editable field 

c o L o r_b o x 

sets the colours of a graphics text field 

readst r__b ox 

returns the text component of an editable field 

readbu t_box 

returns the state of a button 

a d r_b o x 

returns the address of a dialog box 
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Line A graphics functions 


V— 










L i n e a 0 
Lineal 
L i n e a 2 
L i n ea 3 
L i n e a 4 
L i n e a 5 
L i n ea 6 
L i n e a 7 
L i n e a 8 
L i n e a 9 
L i n e a a 
L i n e a b 
L i n ea c 
L i n e a d 
L i n e a e 
L i n e a f 


initialises the lineA routines 
plots a point 

returns the colour of a point 

draws a line 

draws a horizontal line 

draws a filled rectangle 

draws a filled polygon 

1 blits’ a rectangle 

writes a character 

shows the mouse 

hides the mouse 

modifies the mouse form 

defines a sprite 

displays a sprite 

copies raster form 

seed fill 


Menu Functions 


i n i t_me n u 
t i t L e_m e n u 
i t em_me n u 
dra w_m e n u 
d e L e t e_me n u 
e na b L e_me n u 
c h e c k_m e n u 
s e l e c t_me n u 


creates a menu 

adds a title to a menu 

adds an item to a particular menu title 

displays the menu bar 

de-installs the menu bar 

‘greys’ a menu item 

places a tick in front of a menu item 

select/de-select a menu title 


Rectangle functions 

rect_intersect finds the intersection of two rectangles 


rec t_u ni on 
rec t_po i n t 
r e c t _ i ni t 

Resource File 

rs drawalert 


finds the union of two rectangles 
returns whether a point is within a rectangle 
initialises a rectangle structure 

functions 

draws an alert 


r s_d rawobject draws an object or objects from an object tree 
r s_d rawdial draws a dialog box 
r s_e rasedial erases a dialog box 
r s_a d d r d i a l returns the address of a dialog box 

r s_a ddralert returns the address of a dialog box 

rs_addredi t returns the addess of an editable string 
r s_a ddrbutton gives the address of the text of a string or button 
r s_o b j x y w h returns the co-ordinates of an object 

r s_o b j s t a t e returns whether an object is selected or not 

r s o b j s e L e c t selects an object 

r s o bjunselect de-selects an object 
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Window handling functions 


ope n_w i n d o w 
c L ose_wi ndow 
c L e a r_w i ndow 
p r i n t_w i n d o w 
pos_wi ndow 
si z e_w i ndow 


opens a window 
closes a window 

clears the work area of the window 
displays a string in a window 
positions the text cursor of the window 
returns the size of the work area of the window 


Miscellaneous functions 

draw draws a line on the screen 

mouse returns the mouse position 

event waits for an event 

time r_v a l u e returns the value of the interrupt timer 


4.1.2 

ANSI file handling routines 

Opening and Closing files 

f open 

open a file 

f c L o s e 

close a file 

f do p e n 

open a file that has been opened using open 

f reopen 

close and then open a file 

fcloseall 

close all files 

Reading 


f read 

read bytes from a file 

f g e t c 

read a character from a file 

g e t c 

read a character from the standard input 

u n g e t c 

put back a character so that the last one will be 


read again 

fgetchar 

read a character from a file 

getchar 

read a character from the standard input 

f g e t s 

read a string of characters from a file 

gets 

read a string of characters from the standard 


input 

f s c a n f 

formatted input from a file 

scant 

formatted input from the standard input 
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Writing 


f w p i t e 
f pu t c 
pu t c 

fputchar 
putchar 
f pu t s 
puts 
f p r i n t f 
p r i n t f 

write bytes to a file 

write a single character to a file 

write a single character to the standard output 

write a character to a file 

write a single character to the standard output 

write a string to a file 

write a string to the standard output 

formatted output to a file 

formatted output to the standard output 

Standard files 


s t d i n 
s tdou t 
stderr 
s t d a u x 
stdprn 

Standard input file 
Standard output file 
Standard error file 
Serial device 
Printer device 

Positioning within a file 

f s e e k 
f tel L 
rewind 
f f L u s h 
flushall 

moves to a particular byte in a file 
returns the current position within a file 
moves to the beginning of a file 
writes any remaining bytes in a file’s buffer 
perform a f f l u s h for all open files 

Error handling 


f eof 
f error 
clrerr 
errno 

returns whether at the end of a file 
tests whether an error has occurred 
cancels an error condition 
describes the last error 

Various 


s e t bu f 
s e t n b u f 
c p r i n t f 
c s c a n f 
remove 

changes the i/o buffer for a file 
suppress i/o buffering for a file 
formatted output to the screen 
formatted input from the keyboard 
delete a file 


Library Summary 


HiSoft C 


Page 139 


4.1.3 

Unix functions 

Opening and Closing files 

open 

open a file 

creat 

create a file 

close 

close a file 

d u p 

duplicate a file handle 

dup2 

force a file handle to refer to another file 

f i l e n o 

return the file handle of a file that has been opened 


with fopen 

Reading and Writing 

read 

read bytes from a file 

write 

write bytes to a file 

l s e e k 

position within a file 

tell 

return the current position of a file 

File operations 

access 

read the access attributes of a file 

c h mod 

change the access attributes of a file 

rename 

change the name of a file 

unlink 

delete a file 

Directory 

operations 

g e t c wd 

read the current directory 

c h d i r 

change the current directory 

m k d i r 

create a new directory 

rmdi r 

delete a directory 

4.1.4 

ANSI Mathematical functions 

Trigonometric functions 

s i n 

sine 

cos 

cosine 

tan 

tangent 

a c o s 

inverse (arc) cosine 

a s i n 

inverse (arc) sine 

a t a n 

inverse (arc) tangent 

a t a n 2 

special form of inverse (arc) tangent 
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Exponential functions 


exp 
Log 
L og 1 0 
p o w 
sqrt 
s i n h 
cosh 
t a n h 


raise to the power of e 
natural logarithm (to base e) 
logarithm to base 1 0 
raise to the power 
square root 
hyberbolic sine 
hyberbolic cosine 
hyberbolic tangent 


Floating 

floor 
ceil 
tabs 
f mod 
m o d f 
L d e x p 
f r e x p 
ma t h e r r 
dqsort 


point manipulation routines 

nearest whole number (rounds down) 

nearest whole number (rounds up) 

absolute value 

floating point modulo 

return the whole and fractional part 

create a float given a mantissa and exponent 

return the mantissa and exponent of a float 

the error that occurred with a maths function 

sort an array of double precision numbers 




Integer functions 


a b s 
i abs 
Labs 
max 
m i n 
rand 
s r a n d 
s q s o r t 
Lqsort 


absolute value 

absolute value 

absolute value 

larger of two integers 

smaller of two integers 

generates a random number 

intialise the random number generator 

sort an array of short integers 

sort an array of long integers 



4.1.5 

String functions 


Numeric/string conversions 


s s c a n f 

converts from a string to numeric (integer, float 
etc) 


s p r i n t f 

converts from numerics to strings 


a t o f 

converts from ascii to float 


a t o i 

converts from float to ascii 


a t o L 

converts from string to a long integer 

s t r t o L 

converts from string to a long integer 

e c v t 

converts from float to string 


f c v t 

converts from float to string 


g c v t 

converts from float to string 
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String Copy functions 


strcpy 

strncpy 

strcat 

strncat 


copy from one string to another 
copy from one string to another 
copy from one string to the end of another 
copy from one string to the end of another 


Search functions 


strtok 

strspn 

strcspn 

strchr 


splits a string into words 
counts particular characters in a string 
counts all but particular characters in a string 
searches for a character within a string 


String comparison functions 

strcmp compare two strings 

strncmp compare two strings 

stricmp compare two strings ignoring upper/lower case 

strnicmp compare two strings ignoring upper/lower case 


Miscellaneous 

strlen 

strlwr 

strupr 

strrev 

strti me 

strdate 

strgetfn 

strspLf n 

tqsort 


string functions 

return the length of a string 
upper case a string 
lower case a string 
reverse a string 

create a string containing the current time 
create a string containing the current time 
create a file name from its components 
split a file name into its components 
sort a table of strings 
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4.1.6 

Character functions 

Testing characters 

i s a l p h a 

tests if a character is alphabetic 

i s a L n u m 

tests if a character is numeric 

i slower 

tests if a character is a lower case letter 

i supper 

tests if a character is an upper case letter 

i s p u n c t 

tests if a character is a punctuation symbol 

i s s p a c e 

tests if a character is a space 

i s d i g i t 

tests if a character is a digit 

i s x d i g i t 

tests if a character is a hexadecimal digit 

i s c sy m 

tests if a character is valid in C identifiers 

i s c s y m f 

tests if a character is valid at the front of C 


identifiers 

i s p r i n t 

tests if a character is printable 

i s a s c i i 

tests if a character is a valid ascii character 

i s g r a p h 

tests if a character is a graphics character 

i scntr l 

tests if a character is a control character 

Modifying 

characters 

tolower 

converts to lower case 

toupper 

converts to upper case 

t o a s c i i 

converts to ascii 

4.1.7 

Memory functions 


Memory allocation 


ma l l 0 C 

real l o c 
c a l l o c 
free 

allocate a block of memoiy 
allocate a new block of memory 
allocate a block of memory filled with zeros 
free a block of memory 

Block manipulation 

m e m cm p 
m e m c h r 
m e m c p y 
m e m s e t 
m em c c py 
r epmem 

compare two blocks of memoiy 

find a character within a block of memory 

copy a block of memory 

fill an area of memoiy with a particular value 

copy a block until a particular character is found 

initialises a buffer to a given value 

Program 

Termnation 

abort 

exit 

terminate the program 
terminate the program 
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4.1.8 

GEMDOS functions 

gemdos 

bios 

call a GEMDOS function 
call a BIOS function 


X b i 0 s call an XBIOS function 

Character input/output routines 

B c o n i n wait for a character from a specified device 


B c o n o u t 
Bconstat 
B cos t a t 

output a character to a specified device 
return the input status of a specified device 
return the state of an output device 


Reading the keyboard 


C c o n i n 
Crawcin 

wait for a character from the keyboard with echo 
wait for a character from the keyboard without 

C rawi o 

echo 

read a character from the keyboard without 

C n e c i n 
Cconrs 
C c o n i s 

waiting 

wait for a character from the keyboard 

read a string of characters from the keyboard 

returns whether a character is present in the 

Kb ra t e 
I kbd ws 

keyboard buffer 

set the keyboard repeat rate 

send a string of commands to the keyboard 
controller 

Key t b L 
B i o s k e y s 
Kbdvbase 
G e t s h i f t 

set the keyboard mapping table 
re-initialise the keyboard mapping table 
return the address of the keyboard vector table 
return the state of keyboard shift keys 

Screen 

C c o n 0 U t 
C c o n w s 
Cursconf 
Physbase 
L og b a s e 
Get rez 
Setscreen 
SetcoLor 

write a character to the screen 
write a string to the screen 
set the text cursor attributes 

return the memory address of the physical screen 
return the memory address of the logical screen 
return the screen resolution 
change the address or resolution of the screen 
set the palette colours 


Stepa L lette change the palette colours 
V s y n c wait for the next vertical sync pluse 
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Serial and Midi functions 


R S C 0 n f 
C a u x i n 
C a u x o u t 
C a u x i s 
C a u xo s 
Mi di ws 
Iorec 


modify the RS232 configuration 

wait for a character from the serial port 

write a character on the serial port 

return whether a character is ready to be read 

return the serial output status 

write a string to the MIDI port 

return the address of the serial input buffer 


Disk functions 


D s e t d r v 
Dgetdrv 
Df ree 
Rwabs 
F l op rd 
F Lopwr 
F L o p f m t 
FLopver 
Dcreate 
D d e L e t e 
Dsetpath 
Dsetpat h 
F s f i rst 

F s n e x t 

F s e t d t a 

F g e t d t a 
Drvmap 
M e d i a c h 
G e t bp b 
P r o t o b t 


set the current (default) drive 

return the current drive 

return the free space on the speecified drive 

read or write logical disk sectors 

physical read of a floppy disk 

physical write of a floppy disk 

formats a floppy disk track 

physical verify of a floppy disk 

create a new directory 

delete a directory 

set the default path for a particular drive 
return the current path for a particular drive 
read the first file name that matches a given 
filespec 

read the next file name that matches a given 
filespec 

set the dta address (used by Fsf i rst and 
F s n e x t) 

read the dta address 

return the currently connected disk drives 
returns whether a floppy disk has been changed 
returns information about a disk drive 
creates a boot sector image 


File handling 

Fcreate 
F o p e n 
F c L os e 
Fread 
Fwri te 
F s e e k 
F d e L e t e 
Fat t ri b 
Frename 
F d a t i m e 
F d u p 


create a new file 
open a file 
close a file 
read from a file 
write to a file 
position within a file 
delete a file 

return a file’s attributes 
rename a file 

change a file’s time and date stamp 
duplicate a file handle 
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Ff orce 

force a file handle to refer to the same file as 
another handle 

Printing 

Set prt 

configure the printer device 

Cprnout 

write a character to the printer 

Cprnos 

return the printer output status 

P r t b l k 

print a screen dump 

Sound 

G i a c c e s s 

read or write a sound chip control register 

0 n g i b i t 

set one bit of port A of the sound chip 

0 f f g i b i t 

set one bit of port A of the sound chip 

D o s o u n d 

execute a set of sound commands 

Date and Time 

Tgetdate 

read the date 

Tsetdate 

change the date 

T g e 1 1 i m e 

read the current time 

Tset t i me 

set the current time 

G e 1 1 i m e 

read the time and date 

Set t i me 

change the time and date 

Memory allocation and application control 

Ma L l o c 

allocate a block of memory 

Free 

free a block of memory 

M s h r i n k 

return an area of memory to the operating system 

P e x e c 

load and execute a program 

P t e r mO 

terminate the application 

Ptermres 

terminate the application without removing it 
from memory 

Puntaes 

reboot the machine 

Set exc 

set a vector 

Super 

enter supervisor mode 

S u p e x e c 

execute a routine in supervisor mode 

Programing 

the 68901 

M f p i n t 

initialise a 68901 interupt 

J e n a b i n t 

activate an interrupt 

J d i s i n t 

deactivate an interrupt 

X b t i m e r 

initialise a timer 

T i c k c a l 

return the timer calibration value 

Various 

Random 

return a random number 

Ini t mo u s 

initialise the mouse 

Sversion 

return the GEMDOS version number 
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4.1.9 GEM AES functions 

Application control 

a p p L_i n i t 

intialise application 

appl_exi t 

deinitialise application 

a pp l_t record 

start recording events 

a pp l_t play 

execute a string of events 

a p p l_w rite 

send a message 

app L_read 

read a message 

appl_.fi nd 

find an application’s id 

Event Control 

e vn t_d click 

specify the mouse double-click speed 

e vn t__key bd 

wait for a keyboard event 

evnt timer 

wait for a timer event 

evnt button 

wait for a mouse button event 

evnt_mou s e 

wait for a mouse movement event 

evnt_mesag 

wait for an AES message 

e vn t_mu L t i 

wait for more than one event at once 

Form functions 

f o r m_d i a l 

perpare the screen for drawing a dialog box 

f o r m_d o 

let the user ‘fill in’ a form using the AES 

f o rm_a Lert 

display an alert box 

for m_c enter 

centre a form on the screen 

f o rm_e r r o r 

display an error box 

File Selector 


f s e l_i n p u t 

make the GEM file selector appear 

Graphics routines 

g r a f _d r a g box 

move a rectangle using the mouse 

gra f_s L i debox 

move a rectanglel within another rectangle 

gra f _r ubberbox size a rectangle using the mouse 

gra f_g rowbox 

draws an expanding box outline 

graf_s h r i n k b o x draws a shrinking box outline 

graf_movebox 
gra f _w a t c h b o x 
gra f_mou s e 
gra f _ h a n d L e 

draws a moving box outline without finally 
displaying the box 

changes a box’s state when the mouse enters or 
exits a box 

changes the appearance of the mouse and can be 

used to hide and show the mouse 

returns the GEM VDI handle and character cell 

information 

graf_mkstate 

returns the state of the keyboard shift keys 
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Menu functions 


men u_b a r 
men u_t ext 
menu_t no rma l 
men u_i check 
men u_i enable 
menu_regi ster 


displays the menu bar 

changes the text of a menu item 

displays a menu title in inverse or normal 

displays a tick in front of a menu item 

a ‘greys’ a menu item 

adds a desk accessory to the desk menu 


Object functions 


ob j c__a d d 
ob j c__d e l e t e 
ob j c_change 
ob j c__d raw 
Ob j c__o f f s e t 
Ob j c_f i nd 
Ob j c_o rder 
Ob j c_e d i t 


add an object to a tree 
delete an object from a tree 
change an object’s state (ob_state field) 
draw an object and optionally its children 
calculate the co-ordinates of a given object 
find an object given a co-ordinate 
change the order of objects within a tree 
edits a character within an editable field 


Resource routines 


rsrc_load 
rsr c_f r e e 
r s r c_g a d d r 

rsr c_s addr 
rsr c_o b f i x 


load a resource file 

free the memory used by the resource file 

finds the address of an item in a loaded resource 

file 

fixup an address within a loaded resource file 
convert the co-ordinates of an object to pixel co- 
ordinates 


Clipboard functions 

scrp_read find the clipboard directory 

scr p w rite set the clipboard directory 


Shell routines 


she t_e nvrn 
shel_write 
she l_r e a d 
she l_f i nd 


read an environment string 

indicate the next application to be loaded 

find the name of the application 

find a given program in the current path 


Window functions 


w i n d_c r e a t e 
w i nd_open 
w i nd__c lose 
w i n d_d e l e t e 
w i n d_g e t 
w i n d_s e t 
w i n d_f i nd 
w i n d_u pd a t e 
w i n d_c ale 


create a window 
open a window 
close a window 
delete a window 

return information about a window 
modify a window 

find which window is below a given co-ordinate 

forbid screen modifications 

calculate the size of a window’s work area 
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Workstations 

v_o p n v w k 
v_c Lsvwk 
v_c L rwk 
v s_c L i p 
vq_ex t n d 


open virtual workstation 
close virtual workstation 
clear workstation 
set clipping rectangle 

return extra information about the workstation 


Graphics Attributes 


v s_c olor 
vq_co Lor 
v_g e t_p i x e L 
vq_c el Larray 
vq i n_mode 
vsw r_m ode 


set the RGB components of a colour 
return the RGB components of a colour 
return the colour of a point 
return the colours of a cell array 
select a type of input 
select writing mode 


L 










Font functions 

v s t_l o a d_f o n t s load all the font definitions 
v s t_u n l o a d_f o n t s remove the font definitions 
v s t_f o n t select a particular font 

vqt_name find the name of a given font 

vqt_fontinfo return information about the current font 


Graphics text 

v_g text 
v__j u s t i f i e d 
v s t_h eight 
vst_poi n t 
vst_rot a t i on 
v s t_c olor 
v s t_e f f e c t s 
vst_aLi gnment 
v q t__ a ttri butes 
vqt_e x t e n t 
v q t_w i d t h 


display graphics text 

display justified text 

set the character height 

set the character height in points 

set the angle of rotation of characters 

set the colour of graphics text 

set the text graphic effects 

set the vertical text alignment 

return the current text attributes 

return the size of a graphics text string 

return the size of a single character 


Area fill functions 


v f i L Larea 

v_c ontourf i L L 
v sf_i nterior 
vsf_peri meter 
v s f_s t y L e 
vsf_co Lor 
v s f _u d p a t 
v q f _a ttribute 


s 


draw a filled polygon 
seed fill 

select the type of fill 

set whether areas are surrounded by borders 

select the type of fill 

select the colour of fills 

set user defined fill pattern 

return the fill attributes 
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Line drawing functions 


v_p Line 
v s l_t y p e 
v s L__ud sty 
v s l_w i d t h 
v s L_c o Lor 
vs L_ends 
vqL__attributes 


draw one or more lines 

select the line type 

set a user-defined line type 

set the line width 

set the line colour 

set how the ends of lines are to be drawn 
return the line drawing attributes 


Marker functions 


v_pma rker 
vsm_type 
v sm_h eight 
vsm_co Lor 
vqm_a ttributes 


draw a set of markers 

set the type of polymarker 

set the height of polymarkers 

set the colour of polymarkers 

return the current polymarker attributes 


Rectangle drawing functions 


v_c e L Lar ray 
v r_r e c f L 
v_ba r 
v_r bo x 
v r f b o x 


draw an array of rectangles 

draw a filled rectangle without a border 

draw a filled rectangle with a border 

draw an unfilled rectangle with a rounded border 

draw a filled rectangle with a rounded border 


Circular objects 


v_a r c 

v__p i e s L i c e 
v_c i rc Le 
v_e L L a r c 
v_e L L p i e 
v_e L L i p s e 


draw a circular arc 
draw a pie slice 
draw a circle 
draw an elliptical arc 
draw an elliptical pie slice 
draw an ellipse 


Alpha mode routines 


v_e n t e r_c u r 
v_e x i t_cu r 
v_c urtext 
v_r vo n 
v_rvo f f 
v_c u r r i g h t 
v_c urLef t 
v_c urup 
v_c urdown 
v_c urhome 
v_e e o L 
v_e e o s 
v q_c h c e L L s 
v s_c u raddress 
vq_cu raddress 


enter alpha mode 
exit alpha mode 
draw alpha text 
inverse video on 
inverse video off 
cursor right 
cursor left 
cursor up 
cursor down 

home the cursor to the top right 

erase to end of line 

erase to end of screen 

return the size of the screen 

position the cursor 

return the current cursor position 
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Mouse control functions 


v_s how_c 
v_h i d e_c 
v_d spcur 
v__rm c u r 
vsc_f orm 
vq_k e y_s 
vq_mous e 


display the mouse cursor 

remove the mouse cursor 

change the mouse position 

make the mouse disappear 

define a new mouse form 

return the keyboard shift key state 

return the mouse position and button state 


Screen Raster functions 

v r o_c p y f m copy a screen block 

vrt_cpyfm copy a monochrome screen block 

vr_trnfm copy a monochrone screen block (device 

dependent) 


Modifying vectors 

v e x _ t i m v timer vector 

v e x_c urv mouse cursor vector 

v e x_b u t v mouse button vector 

v e x__m o t v mouse movement vector 
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ABORT 


ANSI 


abortO; 

This function stops a running program immediately, 
exit. 


ABS 


ANSI 


ret = abs(val); 
int ret/VaL; 

This function returns the absolute value of the value passed as a parameter. 
Both values are of type int. 



iabs, labs, fabs. 


ACCESS 


UNIX 


ret = access(name,mode); 
int ret, mode; 
char * n a m e ; 

Tests if a file can be acessed for read and/or write depending on the value of 
mode. 


If mode = 0, test the existence of the file 

If mode = 2, test if write access to the file is possible. 

The other UNIX modes are ignored. 

The value returned is 0 if access is possible and -1 if not. In the latter case 
the variable errno contains the corresponding error number. 



chmod, errno. 
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ACOS 


ANSI 


ret = acos(val); 
double r e t , v a l ; 

Calculates the arc-cosine of the value (between -1 and +1) passed as a 
parameter. The value returned is between 0 and pi. 

Both values (the parameter and the result) are double reals. 

If the parameter is not between -1 and +1 the variable errno will indicate 
the error condition. 


L. 

/l\ asin, atan, atan2, errno. 



ADR_BOX 

HiSoft C 



c 

# include <gemlib.h> 
p = a d r_box ( box_no ) ; 
int box no; 

OBJECT * p ; 



This function returns the address of a dialog box. box_ 
box whose address you wish to find. This is the same 
returned by the function i ni t_box. 

.no is the number of 
as the value that is 


The value returned is a pointer to the tree structure of type object. 


/fts Section 3.3, init_box. Help command (adr_box). 


L 

APPLJNIT 

GEM AES 


v_. 


appt_id= appl_init(); 
i n t a p p l_i d ; 

Initialise the application and the GEM AES. 

The value returned is the application's identifier (or appl_id) that is used in 
the application library functions. 

With HiSoft C, it is not necessary to call this function if you wish to use GEM. 
If the value returned is -1 this indicates an error. 


L 
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APPL EXIT 


GEM AES 


ret = appl_exit(); 
i n t ret; 

This function de-initialises the application as far as the AES is concerned. 

If ret = 0 there has been an error. 

When using HiSoft C, there is no need to call this function. 

APPL FIND GEM AES 


a p P l _ i d = appt_init(name); 
int a p p l _ i d ; 
char * n a m e ; 

Finds the application identifier of the named application (normally a desk 
accessory). The name must be at least eight characters, padded with blanks if 
necessary. 


APPL READ GEM AES 


ret = appl_read(appl_id, length, buffer); 
int appl_id, length; 
char * b u f f e r ; 

Reads a message (of the specified length) that has been sent by another 
application. The message is stored in the given buffer. The application 
identifer of the program whose message pipe is being read must be supplied 
as the a pp l_i d parameter. 

The value returned is 0 if an error has occurred. 


APPL TPLAY GEM AES 


appl_tplay(address,n, speed); 
int n, speed; 
char * a d d r e s s ; 

Executes a set of n events that have been stored by the appl.trecord 
function at address at the speed given (100 is normal speed). 


APPL TRECORD GEM AES 


appl_trecord(address,n); 
int n ; 

char *address; 

Stores a set of n events at the address given by the address parameter. 


Page 154 


HiSoft C 


Library Reference 



APPL WRITE GEM AES 


ret = a pp l_w r i t e ( a pp l_i d , t e n g t h , bu f f e r ) ; 
i n t a p p l_i d, Length 
char * b u f f e r ; 

Writes a message (of the length specified from buffer) so that other 
applications may read them. The application identifier of the program that is 
to read the message must be passed as the app l_i d parameter. 

^ — The message can be read using appl_read. 

0 is returned if there is an error. 




& 


appl_read. 


ASIN 


ANSI 












ret = asin(val); 
doub Le ret ,va L; 

Calculates the arc-sine of the value (between -1 and +1) passed as a 
parameter. The value returned is between -pi/ 2 and +pi/2. 

Both values (parameter and return value) are double reals. 

If the value passed is not between - 1 and + 1 then the variable errno will 
indicate that an error has occurred. 



acos, atan, atan2, errno. 


ATAN 


ANSI 


ret = atan(val); 
double r e t , v a L ; 

Calculates the arc-tangent of the value passed as a parameter. The parameter 
and the value returned are double reals. 

The result (in radians) is between -pi/ 2 and +pi/2 inclusive. 





ftJ Find the value of pi 


void ma i n ( ) 

printf("%10.10f% atanCI .)*4); 

> 
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ATAN2 


ANSI 


ret = a t a n 2 ( y , x ) ; 
double x , y , r e t ; 

Calculates the arc-tangent of y divided by x . 

The value returned corresponds to the angle (expressed in radians between 
-pi and +pi) formed by the positive x-axis and the vector from (0.0) to (x,y). 

If x is zero this function returns +pi/2 or-pi/2 depending on the value of 
y. 

It is an error to call this function with both parameters 0 (errno will 
indicate this). 



a tan, asin f acos, ermo. 


ATOF 


ANSI 


x = atofCstring); 
double x; 
char * s t r i n g ; 

This function converts a string of characters to a double precision floating 
point number. 

The string may contain white space, a plus or minus sign followed by a 
standard scientific format number. 

The conversion stops at the first inappropriate character. 



atoi, atol, sscanf. 


ATOI 


ANSI 


i = atoi (string); 
i n t i ; 

char * s t r i n g ; 

This function converts a string of characters to an integer number. 


The string may contain white space, a + or - sign followed by a string of 
digits. 

The conversion stops at the first inappropriate character. 



atof, atoi, sscanf. 
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ANSI 


i = atol(string); 

long i ; 

char * s t ri n g ; 

This function converts a string of characters to a long integer and it works in 
the same way as a t o i . 



atof, sscanf. 


BCONIN 


GEMDOS 


character_code = Bconin(peripherial); 
int peripheral, c h a r a c t e r_c o d e ; 

Waits for a character to be input from the specified peripheral: 


0 

printer (!) 

1 

serial port } 

2 

screen/keyboard 

3 

MIDI 

4 

keyboard processor 

5 

screen j 


The character code returned consists of two bytes. 

The low byte is the ASCII code and the high byte the keyboard scan code. 


BCONOUT GEMDOS 


BconoutCperipheral, character); 
int peripheral, character; 

Writes a character to the given peripheral (see the Be on in function). 


BCONSTAT GEMDOS 


status = Bconstat(peripheral); 
int status, peripheral; 

Returns the input status of the peripheral given as a parameter (see the 
B c o n i n function) . 

The returned value is -1 if the device is ready, 0 otherwise. 
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BCOSTAT 


GEMDOS 


status = Bcostat(peripheral); 
int status, peripheral ; 

Returns the output status of the peripheral given as a parameter (see the 
B con in function). 

The returned value is -1 if the device is ready, 0 otherwise. 

BIOS GEMDOS 


ret = biosCno, argl, a r g 2 . . . ) ; 
int no; 

Long ret ,a rgl ,a rg2, . . . 

Executes a BIOS function using TRAP #13. 

no is the number of the function. 

ret is the value returned by the function. 

argl, arg2... are the parameters for the particular function. 

xbios, gemdos. 

BIOSKEYS 

BioskeysC); 

Re-initialises the standard BIOS key table. 

Keytbl. 



GEMDOS 
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BUTTON BOX HiSoft C 


button_no = button_box(box_no, x, y, button_name, state); 
int b u t t o n_n o , b o x_n o , x , y , s t a t e ; 
char * b u 1 1 o n_n a me ; 

Adds a button to a dialog box that has been initialised by i ni t_box. 

box_.no is the number of the dialog box to which the button is to be added. 

x and y are the co-ordinates (in characters) of the position of the button 
within the box. 

b u 1 1 o n_n a me is the string of characters giving the text of the button, 
state gives the state of the button (the o b_s t a t e value). 

The value returned is the index of the button within the box. 



init_box, Section 3.3.5, Help command (button_b). 


CALLOC 


ANSI 


adr = c a l L o c ( n o_e L eme n t s , element_size); 
char *adr; 

Long no_elements, element_size; 

Allocates a block of memory of size n o_e L e me n t s * e L eme n t_s i z e . 

The block is initialised to zero. 

The value returned is a pointer to the block of memory or 0 if the block 
cannot be allocated. 


The memory is allocated from the system memory whose size is fixed when 
the interpreter is loaded. It is possible to change this value if you have enough 
memory. 



Section 1.4.13, Malloc, Mfree, malloc, free, realloc. 


CAUXIN 


GEMDOS 


character = CauxinO; 
int character; 

Reads a character from the serial port. 
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CAUXIS 

GEMDOS 

status = CauxisC); 
int status; 


Returns whether a character has 
(status = -1) or not (status = 0). 

been received from the serial port 

CAUXOS 

GEMDOS 

status = CauxosO; 
int status; 


Returns whether the serial port is 
(s t a t u s = 0) . 

ready for output (status = -1) or not 

CAUXOUT 

GEMDOS 

Cauxout(character); 
int character; 


Write a character to the serial port. 


CCONIN 

GEMDOS 

character = CconinC); 
int character; 


Wait for a key-press and echo it to the screen. 

Returns the character code read in the same form as that used by Bconin. 

CCONIS 

GEMDOS 

status = CconisC); 
int status; 


Returns whether a character has been typed on the keyboard (status=-l) or 
not (s t a t u s=0). 

CCONOUT 

GEMDOS 

Cconout( character); 
int character; 


Write a character to the screen. 
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CCONRS 

GEMDOS 

Cconrs(string); 
char * s t r i n g ; 


Read a string of characters from the keyboard. 


On entry, the first byte in the string must contain the maximum number of 
characters to read. On exit, the second byte contains the number of 
characters actually read. The actual characters are stored starting at the third 
byte. 

CCONWS 

GEMDOS 

Cconws(string); 
char * s t r i n g ; 


Writes a string of characters to the screen. 


CEIL 

ANSI 


ret = ceil(val); 
double ret/Val; 

Returns the whole number larger or equal to the value of the argument. 

The value returned is a double real with a zero fractional part; not an integer. 



CHDIR 


UNIX 


ret = chdir(path); 
i n t ret; 
char * p a t h ; 

Changes the current directory to the given path. 

This function returns zero if there was no error; otherwise the type of error 
can be found in the variable errno. 



Dsetpath, mkdir t rmdir, getcwd, errno. 
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CHECK MENU HiSoft C 


state = check_menu(entry); 
int state, entry; 

Makes a tick in front of a menu item appear or disappear. The menu must 
have been created with the function init_menu. 

entry is the number of the menu entry as returned by i t e m__m enu. 

The value returned is the new state of the menu entry (1 if ticked, 0 if not). 



init_menu, item_menu. Section 3.4.6, Help command (check_me). 


CHMOD 


UNIX 


//include <fcntl.h> 
ret = chmod(name,mode); 
int ret, mode ; 
char * n a m e ; 

Changes the protection status of the file called name. 

Unlike UNIX, only the write status can be changed. 

If mode = s_i read, the file may only be read. 

If mode = s_i write, the file may only be written. These two values are 
defined in the file fcntl.h. 

On return, ret = 0 if the operation was successful; otherwise the type of error 
can be found in the errno variable. 



CLRERR 


ANSI 


//include <stdio.h> 
clrerr(fp); 

FILE * f p ; 

Resets the error condition on the given stream. 

This function is called clearerr under UNIX system V so be careful when 
porting programs. 



fopen, feof, terror. 
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CLE AR_WI N DOW HiSoft C 


c Lear_wi ndowCwi ndow_no); 
i n t w i n d o w_n o ; 

Clears the interior of a window opened with the HiSoft C function 
open.window. The number of the window to clear must be passed as a 
parameter. 



open_window. Section 3.2.8, Help command (clear_wi). 


CLOSE 


UNIX 


ret = close(fhandle); 
int fhandle, ret; 

Close a file opened using open. 

fhandle is the handle of the file to close as returned by the open function. 

The value returned by close is zero if successful otherwise errno indicates 
which error has occurred. 



open, fopen, fclose, errno. 


CLOSE WINDOW HiSoft C 


c lose_window(window_no) ; 
int win d o w_n o ; 

Closes a window that was opened by the HiSoft C function open_window. 

window_no is the window number as returned by the open_window 
function. 



open_window, Section 3.2.4, Help command (close_wi). 


CNECIN 


GEMDOS 


character = CnecinC); 
int character; 

Read a character from the keyboard. 
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COLORBOX HiSoft C 


co Lor_box(box_no / object_no, bord,text,back); 

This function enables you to change the colour of graphics text of a dialog box 
created by the HiSoft C function i n i t_box. 

b o x_n o is the number of the dialog box created by ini t_box. 

object_no is the object number as returned by gtext_box. 

bord, text, and back are the colours of the border, the text and the 
background respectively. 



init_box, gtext_box. Section 3.3.12. Help command (color_bo). 


COS 


ANSI 


ret = cos(val); 
double ret/val; 

Calculates the cosine of the angle (in radians) that is passed as a parameter. 
The parameter and the result are both double reals. 



COSH 


ANSI 


ret = cosh(val); 
double ret,val; 

Calculates the hyperbolic cosine of its parameter. The parameter and the 
result are both double reals. 

If the argument is too big for the result to be in range the errno variable will 
indicate this error. 



sinh, tanh, errno. 
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CPRINTF 


ANSI 


Length = cpri ntf (format, argl, a r g 2 , . . . ) ; 
int Length; 
char ^format; 

???? argl ,arg2, . . . 

This function writes formatted text. ? ? ? ? indicates that the parameters may 
be of different types. 

The characters are sent direct to the screen, unlike pri ntf where the 
characters are sent to the file stdout. This function avoids the filing system 
as used by p r i n t f . 

Apart from this, this function behaves exactly like p r i n t f . 

See the pri ntf function for the description of the parameters. 


CPRNOS GEMDOS 


status = CprnosC); 
int status; 

Returns whether the printer is ready (status = -l) or busy (status = 0). 


CPRNOUT GEMDOS 


status = Cprnout(character); 
int status, character; 

Writes a character to the printer. The return value indicates that the 
character has been printed (status = -1) or that the printer is busy 
(s t a t u s = 0) . 


CRAWCIN GEMDOS 


character = CrawcinC); 
int character; 

Waits for a character from the keyboard. The full scan code is returned (See 
B c o n i n) . 
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CRAWIO 


GEMDOS 


character = Crawio(parameter); 
int character, parameter; 

Writes a character to the screen with the ASCII code passed as parameter. 

Or... reads a character from the keyboard if parameter is -1. In this case the 
value returned is the scan code (see Be on in) or 0 if there has been no key 
pressed. The function returns immediately if no character has been typed. 


CREAT UNIX 


^include <fcntl.h> 
fhandle = creat(name,mode); 
int fhandle, mode; 
char *name; 

This function creates and opens for write a new file with the given name. If 
the file already exists it is deleted. 

The file is always opened for write. 

The access privileges for the file are fixed by the value of mode: 


S_I READ 

the file is read only 

S_I READ | S_ I WRITE 
or 0 

both read and write is possible 

i 


fhandle is the file handle associated with the created file and is the return 
value of the function. 

If the value returned is -1, the file could not be created. The errno variable 
will indicate the type of error. 



Fcreate, fopen, chmod. 


CSCANF 


ANSI 


n = cscanf (format, argl, arg2, 
int n ; 

char ^format; 

???? arg1,arg2; 

This function is equivalent to scanf except that the characters are read 
directly from the keyboard rather than via the file s t d i n . 

? ? ? ? indicates that the parameters may be of different types. 

See scanf for a description of the parameters. 
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CURSCONF 


GEMDOS 


ret = Cursconf (period, attribute); 
int ret, period, attribute; 

Sets the text cursor attributes depending on the value of attribute: 


0 

the cursor is invisible 

1 

the cursor is displayed 

2 

flashing cursor 

3 

non-flashing cursor 

4 

set the flash period 

5 

the function returns the current flash! 
period 


DCREAE 


GEMDOS 


ret = D c r e a t e ( d i r e c t o ry_n a me ) ; 
int ret; 

char * d i r e c t o r y_n a me ; 

Creates a directory whose name is passed as a parameter. 
The value returned is zero if the operation was successful. 


DDELETE 


GEMDOS 


ret = D d e L e t e ( d i r e c t o r y__n a me ) ; 
int ret; 

char *di rectory_name; 

Deletes the directory whose name is passed as a parameter. 

The value returned is zero if the operation was successful. 

HiSoft C 


DELETE MENU 


ret = de Lete_menu( ); 
int ret; 

Deletes a menu that has been created with init_menu and drawn with 
d r a w_m e n u . 

The value returned by this function is 1 if the operation was successful and 0 
if not. 



init_menu, drawjmenu, Section 3.4.5, Help command (delete_m). 
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DFREE 


GEMDOS 


ret = DfreeCbuffer, disk_no); 
int ret, dis k_n o ; 

Long bufferC4]; 

This function returns information about the disk given by disk_no. The 
numbers used are 


0 

the current drive 

— 

drive A 

2 

drive B 

3 

drive C 


etc. 

The function stores the information in the array buffer as follows 


bufferCOl 

the number of free clusters on the disk 

bufferCIU 

the total number of clusters on the disk (351 or 
711 for floppies) 

bufferC21 

the sector size in bytes (normally 512) 

bufferC31 

the number of sectors per cluster (normally 2) 


The value returned by the function is 0 if the operation was successful. 


DGETDRV GEMDOS 


drive_no = DgetdrvO; 
i n t d r i v e_n o ; 

Returns the number of the current disk drive (0=A, 1=B, 2=C, etc.) 


DGETPATH GEMDOS 


ret = Dgetpath (path_name / dri ve_no); 
int drive_no, ret; 
char * pa t h_n a me ; 

Returns the default path name (in path_name) for the specified drive 
according to the value of drive_no (0=current disk, 1=A, 2=B, 3=C etc.). 

The value returned is zero if the operation was successful. 
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DOSOUND 


GEMDOS 


Dosound(command_stri ng); 
char * comma n d_s t r i ng ; 

Executes a set of sound commands passes as a string of characters to the 
function as a parameter. 

A command consists of a command byte followed by optional parameters that 
depend on the command. 

Commands 0 to 15 have a parameter that is to be written to one of the 16 
sound chip registers (command 0 for register 0, command 1 for register 1 
etc.). 

Command 128 has a byte argument that is written to a temporary register. 

Command 129 is a form of loop statement and has three byte arguments. The 
first is the register to use (the temporary register is initially assigned to this 
register). The second argument is the increment and the third the 
termination valuerThe increment is added to the appropriate register until 
the termination value is reached. How frequently these assignments are 
executed is set by the commands below. 

Commands 130 to 255 have one argument. If this is zero then the sound is 
terminated; otherwise the argument is taken as how frequently sound 
commands are to be executed in fiftieths of a second. 


DQSORT 


UNIX 


d q s o r t ( a r r , n ) ; 
double * a r r ; 
i n t n ; 

Sorts an array of n double precision floating point numbers into ascending 
order. 



lqsort, sqsort, tqsort. 


DRAW 


HiSoft C 


draw(x1,y1,x2,y2); 
int x1,y1,x2,y2; 

Draws a line between the two points (xl, yl) and (x2, y 2) . 
This function does not return a value. 



v_pline. Section 3.2.10, Help command (draw). 
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DRAW BOX HiSoft C 


ob ject_no = d ra w_box ( box_no ) ; 
int object_no, box_no; 


Draws a dialog box created by i n i t_box. 



Section 3.3.6, Help command (draw_box). 


DRAW MENU HiSoft C 


ret = draw_menu(); 
int ret; 

Makes a menu bar created using init_menu appear. It is then possible to 
click on menu items. 

The value returned by this function is 1 if all went well and 0 otherwise. 



delete_menu, init_menu. Section 3.4.5, Help command (draw_men). 


DRVMAP 


GEMDOS 


a c t i v e_d r i v e s = drvmapO; 
int a c t i v e_d rives; 

Returns which disk drives are present in a c t i ve_d r i ve s . 

The value returned has bit 0 set if drive A exists, bit 1 set if drive B exists, 
etc. 


DSETDRV 


GEMDOS 


a c t i v e__d r i v e s = Dsetdrv(drive_no); 
int drive_no, acti ve_drives; 

Set the default disk drive (drive_no= 0 for drive A, 1 for drive B etc.). 
The value returned indicates which drives are active (see drvmap). 


Page 170 


HiSoft C 


Library Reference 


DSETPATH 


GEMDOS 


ret = Dse t pa t h ( pa t h_name ) ; 
i n t ret; 

char *pa t h_name ; 

Sets the default directory for the default drive to be pathname. 
The value returned is zero if the operation was successful. 


DUP 


UNIX 


new_handle = dup(handle); 
int new_ handle, handle; 

Duplicates a file handle. The new file handle (returned by the function) is 
associated with the same file as the original one. 

If the duplication isn’t possible - 1 is returned and errno contains the reason 
for the error. 



Fdup, Fforce, fdopen, errno. 



See std. 


DUP2 


UNIX 


ret = dup2(new_ handle, handle); 
int n e w_h a n d l e , h a n d l e ; 

Forces the file handle to point to the same file as n e w_h a n d l e . 

If an error occurs -1 is returned and errno indicates which error occurred. 



Fdup, Fforce, fdopen, errno. 


BO See std. 
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ECVT 


UNIX 


p = ecvt(a,prec,decpt,sign); 
int prec,*sign,*decpt; 
double a; 
char * p ; 

Converts the floating point number a to a string of characters consisting only 
of digits. 

prec is the number of significant digits desired. 

On return, decpt indicates where the decimal point would appear from the 
start of the string, sign contains zero if the number a was positive or zero, p 
points to the string of characters. 


EDIT BOX 


HiSoft C 


object_no = e d i t_bo x ( b o x_n o , x,y, text, template, 
Legal_chars); 

int object_no, box_no, x, y; 

char * t e x t , ^template, *legal_char; 

Adds an editable text field to a dialog box created by ini t_box. 

bo x_n o indicates the dialog box to which the editable text is added. 

x and y are the character co-ordinates of the text relative to the top left 
comer of the box. 


text indicates the text to be displayed, template describes the format of 
the field, lega l_chars describes which characters may be entered, 
o b j e c t_n o is the index of the object within the box. 



initjbox. 


Section 3.3.8, 


Help command (edit_box). 
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ENABLE MENU 


HiSoft C 


status = e n a b L e_me n u ( e n t ry_n o ) ; 
int status, entry_no; 

Makes a menu appear in grey or makes it appear as normal if it was already 
grey. 

The menu must be created using the i ni t_menu function. 

ent ry_no is the index of the menu entry to change as returned by 
i t e m_m enu. 

The returned value is the new state of the menu: 1 if grey 0 if not. 



init_menu, item_menu, Section 3.4.6, Help command (enable_m). 


ERRNO 


UNIX 


#include <error.h> 
ermo; 

errno is an integer variable defined by HiSoft C. It is initialised to zero; it is 
set to a non-zero value following an error. 

When a system function fails (generally returning -1), the reason for the error 
is stored in errno. This variable is not reset to zero when a function 
terminates correctly, thus it should only be checked when an error has 
occurred. 

HiSoft C does not use all the UNIX error codes. In the following list of all the 
codes, those that are not used by HiSoft C are prefixed with an asterisk. The 
names of the errors (following the UNIX standard) are defined in the file 
error.h. 


1 

•* E P E R M 

The user doesn’t have permission to access this file. 

2 

NOENT 

The file name specified does not exist. 

3 

* E S R C H 

Process does not exist. 

4 

E I NT R 

The function has been interrupted by an event. 

5 

E I 0 

I/O error during a read or write. This error is not 
detected until the following call to the function. 

6 

ENXIO 

Non-existent peripheral or not working (no disk in 
drive). 

7 

E2BIG 

An argument to the function is too large. 

8 

*EN0EXEC 

Error in the format of an executable file. 

9 

EBAD F 

Invalid file handle. This error is given if the file is not 
open, or a read is attempted on a write-only file or vice 
versa. 
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10 

* E C H I LD 

No child process. [ 

1 1 

* E A G A I N 

No more processes available. 

12 

ENOMEM 

The program is asking for more memory than is | 
available. j 

13 

EACCES 

Attempt to access a file in a way that does not 1 
correspond to the access privileges of the file. For | 
example, trying to open a read-only file for write. 

14 

E FAULT 

Memory access error during a system call (access to an [ 
illegal address) whilst trying to access its parameters. j 

15 

ENOTBLK 

File name used instead of a device identifier. 

16 

EBUS Y 

Device busy. I 

17 

EEXIST 

Attempt to create a file which already exists. 

18 

* E X D E V 

Attempt to mount a volume that is already present on | 
another device. 

19 

NODEV 

Trying to execute a system function that is j 
inappropriate for this device (reading from a write-only [ 
device). 

20 

ENOTD I R 

Using an invalid name when a directory is required. For j 
example, the path name required by the chdi r j 
command. 

21 

E I S D I R 

Trying to write to a directory. 

22 

E I N V A L 

Invalid function argument. For example, trying to read | 
or write a file after Lseek has returned a negative j 
value, or a bad argument to a mathematical function. 

23 

E N F I L E 

The table of open files is full. No more files may be j 
opened. 

24 

EM F I LE 

A process may not open more than 20 files 
simultaneously. | 

25 

* E N 0 T T Y 

Not a terminal. 

26 

ETXTBUSY 

Opening a file that is already opened. 

27 

* E FB I G 

File too long. 

28 

ENOSPC 

Device full (no disk space). 

29 

ESPI PE 

Call to a seek function for a device that only supports J 
sequential access. j 

30 

EROFS 

Attempt to write or modify for a device which only j 
supports read access. 

31 

* E M L I N K 

Too many links to a file. 

32 

★ E P I P E 

Writing to a pipe without a process to read it. 

33 

EDOM 

The argument of a mathematical function is outside its | 
defined domain. 

34 

ERANGE 

The value calculated by a function is too big to be [ 
represented by the machine. 
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EVENT 


HiSoft C 


event_type = event (&menu_ti t Le, 8menu_entry, 
window, & k e y , Sxclick, &yclick); 
int menu_ti t Le, menu_entry; 
int key, xclick, yclick; 
int event_type; 
short windowC6U; 

This function waits for an event as described in Section 3.5.3. 



evntjmulti, Section 3.5, Help command (event). 


EVNT.BUTTON GEM AES 


num = evnt_button(no_c L i cks, mask, state_requi red, 

S x , & y , & b u 1 1 o n_s t a t e , & k e y b o a r d_s t a t e ) ; 

int num, no_cli cks, mask, state_requi red; 
short x, y, b u 1 1 o n_s t a t e , k e y b o a r d_s t a t e ; 

Wait for a given mouse button state. 

n o_c Licks is the number of clicks to wait for. 

mask indicates which buttons to test (l=left, 2=right, 3=both). 

state_requi red indicates if the function should return when the button is 
pressed (0) or when it is released (1). 

num is the number of clicks that actually occurred. 

x and y are the mouse co-ordinates when the mouse was clicked, 

button_state indicates which mouse buttons were pressed when the 
button was pressed or released. 

k e y b o a r d_s t a t e indicates the state of the right shift (bit 0), left shift (bit 
1), Control (bit 2) and Alternate (bit 3) keys. The corresponding bit is set if 
the given key is down. 
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EVNT DCLICK GEM AES 


interval = e vn t_d c l i c k ( n e w_i n t e r va l , set); 
int interval, new_ interval, set; 

Sets or returns the double-click speed of the mouse. 

If s e t is 1 then new.interval is used to set the double-click speed 
between 0 (450 ms) and 4 (165 ms). 

If set is 0 then the current speed is being requested. 

In either case, interval is returned as the new double-click speed. 


EVNT KEYBD GEM AES 


key_code = evn t_keybd ( ) ; 
int key_code; 

This function waits for a key to pressed on the keyboard. It returns a 16 bit 
code. The bottom 8 bits are the ASCII code for the key. 


EVNT MESAG GEM AES 


evnt_mesag(buffer); 
short bufferC81; 

Wait for a window or menu event. 

The description of the message is contained in the array buffer. 


EVNT MOUSE GEM AES 


e v n t_mo u s e ( s o r t , rx,ry,rw,rh, 

8x, 8y, 8 b u t t o n_s t a t e , 8 k e y b o a r d_s t a t e ) ; 

int sort,rx,ry,rw,rh 

short x, y, b u 1 1 o n_s t a t e , keyboa rd_state; 

Wait for the mouse to enter or leave the specified rectangle. 

sort indicates whether the function should return when the mouse enters 
(0) or leaves (1) the rectangle. 

rx,ry,rw,rh give the co-ordinates of the rectangle. 

button_state indicates which mouse buttons were pressed when the 
mouse moved across the rectangle border. 

key boa r d_s t a t e indicates the state of the right shift (bit 0), left shift (bit 
1), Control (bit 2) and Alternate (bit 3) keys. The corresponding bit is set if 
the given key is down. 
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1 

z 

> 

LU 

MULTI 

1 GEM 

AES 


which_events = evnt_mu L t i ( even t_types, 
no_clicks, mask, s t a t e_requ i red, 
sort1,rx1,ry1,rw1,rh1, 
sort2,rx2,ry2,rw2,rh2, 
buffer, 
time1,time2, 

8x,8y, 

8but ton_sta te, 8keyboard_state, 

8key_code, 

8num) ; 

Wait for one or more events. 

even t_t y p e s indicates the types of event to wait for: l=keybd, 2=button, 
4=mousel, 8=mouse2, 16=mesag, 32=timer. To wait for more than one 
event, or (I) them together. 

The other parameters are the same as described under the functions 
evnt_keybd, evnt_mouse, evnt_timer, evnt_mesag and e v n t_b u 1 1 o n . 

The value returned is the event or events that occurred. 


event. 



/* 

evn t_but ton 

*/ 

/* 

evnt_mouse 

*/ 

/* 

evn t_mouse 

*/ 

/* 

evn t_mesag 

*/ 

/* 

evn t_t i me r 

*/ 


EVNT_TIMER GEM AES 


evnt_timer (timel , t i m e 2 ) ; 
unsigned int timel, t i m e 2 ; 

Wait for a time interval. The interval is given by time1+65536*time2 
milliseconds, tempi and temp 2 must be less than 65536. 


EXIT 


ANSI 


exit(return_code); 
int retur n_c od e ; 

This function terminates the current program. 

The parameter return_code is the code returned to the calling program; 
this is ignored by HiSoft C. 



abort, stop. 
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EXP 


ANSI 


ret = exp(val); 
double ret, val; 

This function returns e to the power val. 

The parameter and the result are both double reals. 

If the parameter is too large, the variable err no will indicate the reason for 
the error. 

log, loglO, pow, errno. 

FATTRIB 


GEMDOS 



ret = F a t t r i b ( f i l e_n ame , set, attrs); 
Reads (set=0) or sets (s e t =1) the attributes of a file. 
The possible attributes (which may be combined) are 


0 

the current drive 

2 

file is hidden 

4 

file is system 

8 

user file 

16 

file is a directory 

32 

file has been written and closed 


FABS 


ANSI 


ret = fabs(val); 
double ret, val; 

This function returns the absolute value of the function. 
The parameter and the result are both double reals. 



iabs, labs, abs. 
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FCLOSE 


ANSI 


^include <stdio.h> 
ret = fclose(fp); 
i n t ret; 

FILE * f p; 

Close a file that has been opened with f o p e n . 
The file to close is given via the file pointer f p . 


If the value returned is not zero, then an error has occurred during the close 
and the errno variable may be inspected to find out why. 



fcloseall, fopen, open, close, errno. 


FCLOSE 


GEMDOS 


ret = FcLose(f handle); 
int ret, fhandle; 

Close a file opened with Fopen. 

The value returned is zero if the file was closed correctly. 


FCLOSEALL 


ANSI 


^include <stdio.h> 
no = fcloseall(fp); 
int no; 

FILE * f p ; 

Close all the files that have been opened with fopen. 

The returned value indicates how many files have been closed. If this value is 
-1 then an error has occurred whilst closing a file and errno may be 
inspected to find out why. 

A 

c-S-i All the files are closed even stdin, stdout etc. After a call to this 
function all the standard file input/output routines won’t work unless you 
explicitly re-open them. 



fclose, fopen, open, close, errno. 
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FCREATE 

GEMDOS 

f i l e_h a n d l e = F c r e a t e ( f i l e_n a m e , attributes); 
int file_handle, attributes ; 
char *f i l e_name; 

Creates and opens a file called f i le.name 
Fa 1 1 r i b. 

with the given attributes. See 

If the file already exists then it is deleted. 


The function returns the file handle for use when writing and closing the file. 

FCVT 

UNIX 

p = fcvt.Ca, n, & d e c p t , Ssign); 
int n,sign,decpt; 
double a; 
char * p ; 


This function is identical to ecvt except 
number of digits after the decimal point 

that n indicates the required 

ecvt. 


FDATIME 

GEMDOS 


F d a t i me ( d a t e_t i me , file_handle, set); 
int fit e_ handle, set; 
char *date_time; 

Sets (s e t =0) or returns (set = l) the file’s creation date and time. 

The date and time are returned in the buffer pointed to by date_time (see 
Tgetdate for the format) . 


GEMDOS 


FDELETE 


ret = FdeleteCf i le_name); 
int ret; 

char * f i l e_n a m e ; 

Deletes the file whose name is passed as a parameter. 
The value returned is 0 if the operation was successful. 
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FDOPEN 


k 


ANSI 


V 


k 


^include <stdio.h> 

fp = f dop e n ( f i t e_h a n d L e , mode); 

i nt f i Le_hand Le; 

FILE * f p ; 
char * m o d e ; 

This function enables you to use the ANSI file functions (terror, fprintf, 
f g e t s , etc) with a file that has already been opened with the UNIX open 
function. 

It is therefore a transformation from a UNIX file handle to a ANSI file pointer. 

f i l e_h a n d L e is the file handle of a file that has been opened using open. 

mode gives the type of access for the file. Its value is the same as that 
described under fopen. 

f p is the returned value; this is the new file pointer for the same file. 

If an error occurs the value returned is 0. See errno for which error. 



open, fopen, fileno. 



see std. 


GEMDOS 


FDUP 


_ 


new_handle = F d u p ( f i l e_h a n d l e ) ; 
int new_handle, f i Le_handle; 

Duplicates a file handle. file_handle and new_hand Le will both use the 
same file. 

This function is very useful for re-directing the standard input/output files, 
dup. 
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FEOF 


ANSI 


^include <stdio.h> 
ret = feofCfp); 
i n t ret; 

FILE * f p ; 

Tests whether the a file given by the file pointer f p is at the end of the file. 
This function returns the value 0 if the end of the file has not been reached. 
The file concerned must be opened using fopen. 



terror. 


FERROR 


ANSI 


^include <stdio.h> 
ret = ferror(fp); 
i n t ret; 

FILE * f p ; 

Tests whether an error has occurred during i/o to the file f p . 
This function returns 0 if an error hasn’t occurred on this file. 
The file must have been opened using fopen. 

/j\ feof. 


FFLUSH 


ANSI 


^include <stdio.h> 
ret = fflush(fp); 
i n t ret; 

FILE * f p ; 

Empties the output buffer for the file given by f p. If the buffer isn’t already 
empty the information in it is written to disk. 

If the operation is successful 0 is returned. Otherwise the value e o f is 
returned; for example, this will happen if the file is not open for write. In 
this case errno will indicate which error has occurred. 



fflushall, fclose, errno. 
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FFLUSHALL 


ANSI 


//include <stdio.h> 
no = fflushallO; 
i n t no ; 

Flushes the output buffer for all files opened with fopen. 

If the operation was successful the number of files closed is returned. 

Otherwise the value EOF is returned. This will occur if one of the files is not 
open for write. The variable errno can be examined to find out the error that 
has occurred. 



fflush, fcloseall, errno. 


FFORCE 


GEMDOS 


ret = FforceCne w_ handle, handle); 
int n e w_h a n d l e , h a n d l e ; 

Forces the given file handle to point to the same file as new_hand le. 
If an error occurs the value returned is negative, otherwise it is 0. 


FGETC 


ANSI 


//include <stdio.h> 
c = getc(fp); 
c = fgetc(fp); 
int c ; 

FILE * f p ; 

Reads a character for the file f p that has been opened using fopen. 

The value EOF is returned if the end of the file is reached or an error occurs. 
If an error has occurred the variable errno indicates which error. 

Be careful not to assign the result of this function to a variable of type char. If 
you do this end of file detection will be impossible. 

The two functions getc and f g e t c are equivalent. 



fgetchar. 
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a£ J The program below reads a file byte by byte and displays it on the screen 
byte by byte. An equivalent but much faster version is given under the 
function fgets. 


//include <stdio. 
void mainO 

FILE * f p ; 
i n t i ; 

h > 

fp = fopenC 
if ( ! f p ) 

"test.txt". 

p r i n t f ( ' 

'Fatal error 

e x i t ( 0 ) 

/ 

> 


while C(i = 

getc(fp)) != 


putchar(i); 

fclose(fp); 


> 


FGETCHAR 


ANSI 


c = getcharC); 
c = fgetcharO; 
i n t c ; 

Reads a character from the file stdi n (the keyboard by default). 
The two functions getchar and f getchar are equivalent. 


& 


fgetc. 


IFGETDTA 


GEMDOS 


buffer_adr = FgetdtaC); 
char *buffe r_a dr; 

This function returns the address of the buffer used by the GEMDOS 
directory search functions. 


Page 184 


HiSoft C 


Library Reference 


FGETS 


ANSI 


^include <stdio.h> 
p = f g e t s ( bu f f e r , Len, fp); 
char *p, *buffer; 
i n t Len; 

FILE * f p ; 

Reads a string of characters terminated by a new line ('\n ’) from the file 
given by f p. This file must have been opened for read. 

A maximum of Len characters are read. Reading stops if either Len 
characters have been read or a ' \ n ' character is read. A null character 1 \ 0 ' 
is stored instead of the new line or after the last character read. 

The value returned is the same as the buffer unless an error occurs. In this 
case 0 is returned and errno indicates the source of the error. 



gets, fread, errno. 


BO The program below reads a file line by line and displays it on the screen 
a line at a time. Compare this with the fgetc example. 

tfincLude <stdio.h> 
void mainO 

FILE * f p ; 

char * p , bufC82D; 

fp = fopenC test.txt" , " r " ) ; 

if ( ! f p ) 

printf ("fataL error"); 
exitCO); 

> 

whiLe (p = fgetsCbuf, 80, fp)) 
printfC" %s" , buf); 
fcLoseCfp); 


FILENO 


ANSI 


tfincLude <stdio.h> 
fd = fiLeno(fp); 
i n t f d ; 

FILE * f p ; 

Returns the file descriptor associated with the file pointer fp that has been 
opened using fopen. 



fdopen. 



see std. 
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FLOOR 


ANSI 


ret = floor(var); 
double ret,var; 

Returns the whole number less than or equal to the value of the argument. 
Although the result has a zero fractional part it is a d o u b l e not an i n t . 

/frs ceil. 


FLOPFMT 


GEMDOS 


ret = FlopfmtCbuffer, 0, drive_no, sectors_per_track, track_no, 
side, reserved_sec tors, 0x87654321, virgin); 
int ret, drive_no, sec tors_per_t rack, track_no, side; 
int reserved_sec tors, virgin; 
char bufferC8192!]; 

Formats a track (track.no) on a floppy (drive.no: 0=A, 1=B) on a given 
side (side). The number of sectors per track (s e c t o r s_p e r_t r a c k) and 
reserved sectors must be specified as parameters, virgin gives the word fill 
value for new sectors. 

The value returned is 0 if the operation succeeded. 


FLOPRD 


GEMDOS 


ret = FloprdCbuffer, 0, drive_no, sector, track, 
side, no_sectors); 

int ret, drive_no, sector, track, side, no_sectors; 
char ^buffer; 

Reads sectors from a given floppy disk and stores the bytes at address 
buffer. This function reads no_sectors starting at the given sector, 
track and side from the drive dri ve_no (A=0, B=l). 

The value returned is zero if the operation was successful. 


FLOPVER 


GEMDOS 


ret = F lopver (buf f e r, 0, dri ve_no, sector, track, 
side, no_sectors) ; 

int ret, dri ve_no, sector, track, side, no_sectors; 
char * b u f f e r ; 

Verifies floppy disk sectors and stores the numbers of those that fail in 
buffer. The other parameters are the same as for F l o p r d . 
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FLOPWR 


GEMDOS 


ret = F t o pw r ( bu f f e r , 0, drive_no, sector, track, 

side, no_s ectors); 

int ret, dri ve_no, sector, track, side, no_sectors; 
char *buffer; 

Writes one or more sectors to a floppy disk from buffer. The other 
parameters are the same as for F l o p r d . 

The value returned is 0 if the write was successful. 


FMOD 


ANSI 


a = fmod(b, c); 
double a, b, c; 

Real number modulus. 









V- 


This function returns b mod c. 

a. b and c satisfy the relation : b = k*c + a. 



C % operator. 


FOPEN 


ANSI 


^include <stdio.h> 
fp = fopen(name,mode); 

FILE * f p ; 

char *name,*mode; 

This function opens a file for the types of i/o given by mode, 
name is the file to access including an optional path specifier, 
mode is a string of one to three characters. 

The first character must be present and should be one of: 


I r 

open for read. 

W 

create and open for write. 

j a 

open for write having moved to the end of the 
file (append). If the file does not exist it is 
created. 


The string may contain the character +. This indicates that the file is opened 
for update (i.e. both read and write). If " r + " is used i/o starts at the 
beginning of the file; if " w + " is used the file is created (any existing file is 
deleted) and if "a + " is used then i/o starts at the end of the file. 
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The mode string may also contain the character " a " and if so the file is 
treated as an ASCII file. In this case when reading CR/LF pairs (OxOd.OxOa) 
are replaced by a single OxOa. When writing, OxOa is expanded to CR/LF. In 
addition Ctrl-Z (Oxl a) is considered to indicate the end of file. Alternatively, 
you may include a " b " and the file will be treated as a binary file, so that no 
conversions will be down. 

Examples : 

" r " open the file for read 

" r + " open a file for read /write 

"ra + " open an ASCII file for read /write. 

"wb" open a new binary file for write 

The value returned by the function is a file pointer for accessing the file that 
has been opened. If this value is 0, the file could not be opened and errno 
will indicate why. 



open, fdopen, freopen, fclose. 


GEMDOS 


FOPEN 


file_handle = Fo p e n ( f i l e_n a me , open_mode); 
int file_handle, open_mode; 
char *file_name; 

Opens the file with name f i Le.name for read and/or write depending on the 
value of open_mode: 


6 

open for read 

l 

open for write 

2 

open for read/write 


The value returned is either a positive file handle or a negative GEMDOS 
error number following an error. 


FORM ALERT GEM AES 


ex i t_bu 1 1 on = f orm_a Lert (default_button, string); 
int exi t_button, d e f a u l t_b u t t o n ; 
char * s t r i n g ; 

Displays an alert dialog box on the screen and waits for user input. 

def au L t_button is the button number that will be returned if the user 
types Return. 

string is a string of characters describing the alert message. 

The returned value is the button selected by the user. 
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V. 

FORM.CENTER 

GEM AES 

k 

^include <gemlib.h> 

f o r m_c e n t e r ( b o x_a d r , &x, &y, &w, 8h); 

OBJECT *box_adr; 
short x,y,w,h; 

Centres a dialog box in the screen. 



box_a d r is the address of the tree to be centred. 

The function returns x,y,w,h as the co-ordinates of the box. 


FORM.DIAL 

GEM AES 

c 

ret = f o rm_d i a l ( t y p e , x1,y1,w1,h1, x2,y2,w2, 

int type, ret; 
int x1,y1,w1,h1; 
int x2,y2,w2,h2; 

h 2 ) ; 

V.j 

Initialise or finish the display of a dialog box. 



FORM_DO 

GEM AES 

C 

V 

# include <gemlib.h> 

ret = f o r m_d o ( d i a L og , field_no); 

int ret, fiel d_no; 

OBJECT *dialog; 


S~ v 

Lets the user interact with a dialog box. 


C 

FORM.ERROR 

GEM AES 


ret = form_error(error_no); 
int ret,erro r_n o ; 



Displays a GEMDOS error message given by error_no. 















1 
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FPRINTF 

ANSI 

U include <stdio.h> 

ten = fprintfCfp, format, arg1,arg2, . . . ); 
i n t L e n ; 

FILE * f p ; 
char *format; 



???? arg1,arg2,... 

Write formatted text to the file given by the file pointer f p . This file must 
have been opened using fopen. 

? ? ? ? indicates that the parameters may be of different types. 

This function is the same as p r i n t f except that the text is written to a file 
rather than to the standard output (the screen by default). 


FPUTC 

ANSI 

^include <stdio.h> 
ret = fputc(c,fp); 
ret = putc(c,fp); 
int c, ret; 



FILE * f p ; 

Writes a character c to a file given by fp. fputc and putc are identical. 

If an error occurs the function returns - 1 and errno indicates the reason for 
the failure. 


fputchar, putchar, errno. 


FPUTCHAR 

ANSI 

c = fgetcharC); 
int c ; 

Reads a file from the standard input (the keyboard by default), 
code of the character is returned by the function. 

/^\ putchar, fputc. 

The ASCII 
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FPUTS 


ANSI 




//include <stdio.h> 
ret = fputs(s,fp); 
i n t ret; 
char * s ; 

FILE * f p ; 

Writes a string of characters to the file given by f p . The file must be opened 
for write. 

If an error occurs this function returns -1 and errno will indicate which 
error. 



fwrite, puts, errno. 


FREAD 


ANSI 




CJ 

\ 




//include <stdio.h> 

num = freadCbuffer, item_size, n, fp); 
int num, n,item_ size; 
char *buffer; 

FILE * f p ; 

Reads n items of size (in bytes) item_size from the file given by fp. This 
file must have been opened with fopen. 

The items are read so long as end of file is not reached or an error does not 
occur. 

buffer is the address where the items are stored. 


The function returns the number of whole blocks read. If this is less than n 
then an error has occurred or the end-of-file has been reached. These two 
cases can be distinguished by using the terror and f eof functions. 



fgets, fgetc, feof, terror, errno. 



FREAD 


GEMDOS 


bytes__read = FreadCfhandle, n, buffer); 
int fhandle, byte s_ read, n; 
char * , buffer; 

Reads n bytes from the file given by fhandle (as returned from Fopen). The 
number of bytes to read is given by n and the bytes read are stored in 
buffer. 

The function’s result is the number of bytes actually read. This value will be 
less than n if an error occurs or the end-of-file is reached. 
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FREE 


ANSI 


ret = free (mem) ; 
char * m e m ; 
i n t ret; 

This function frees a block of memory that has been allocated with ma LLoc, 
calloc or realloc. 

The value passed as a parameter must have been returned by one of the 
allocation functions and must not have already been freed. 

The value returned is 0 if successful ; -1 if an error occurred. 



malloc, calloc, realloc, Malloc, Mfree. 


FRENAME 


GEMDOS 


ret = Frename(0, old_name, new_name); 
i n t ret; 

char *old_name, new_name; 

Renames an existing file o l d_n a m e to have the name n e w_n a m e . 

The value returned is 0 if all is well. 

ANSI 


FREOPEN 


//include <stdio.h> 

fp = f reopenff i le_name, mode, fp) 

FILE *fp,*fp; 

char * f i l e__n a me,*mode; 

Close a file and open another one using the same file pointer. 

The file fp is closed and is immediately re-opened to refer to the file 
f i l e_n a m e in the given access mode. The mode and f i le_name parameters 
are the same as for the fopen function. 


The value returned is the file pointer and is the same as that passed as a 
parameter. 

This function is generally used to redirect the standard input/output files. For 
example to divert screen output (via stdout) to a file. 



fopen, fdopen, dup. 
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FREXP 


v_ 


ANSI 


a = f r e x p ( b , exp); 
double a, b; 
int * e x p ; 

Split a floating point number b into its mantissa a (0.5<=a<1.0) and its 
exponent exp (-1024<e x pel 024). 

The following relation is satisfied: 

b = a * (2 A exp) 


FSCANF 


ANSI 




Vw 




//include <stdio.h> 

n = fscanfCfp, format, argl, a r g 2 , ■ - . ) ; 

int n ; 

FILE * f p ; 

???? * a r g 1 ,*arg2, . . . 

This function is equivalent to scant except that input is taken from the file 
fp rather from the standard input (stdin). 

???? indicates that the parameters may be of different types. 

Note that 

fscanfCstdin, format, argl,. . .) 
is equivalent to 


scant (format,arg1,. . .); 
a scanf, sscanf, cscanf. 






Library Reference 


HiSoft C 


Page 193 


FSEEK 


ANSI 


//include <stdio.h> 

ret = fseekCfp, pos, mode); 

int ret, pos, mode; 

FILE * f p ; 

This function changes where in a file the next read or write will occur. The 
position depends on the mode: 


0 

pos gives the number of bytes from the start 
of the file. 

1 

pos gives the number of bytes from the 
current position. 

2 

pos gives the number of bytes from the end of 
the file (this number must always be 0 or 
negative). 


The value returned by the function is 0 if the operation was successful or 
non-zero if an error occurred in which case errno indicates the type of 
error. 


/t 


When mode =2, the number of bytes must be negative to move to before 


the end of the file. It is not possible to position past the end of file. 



The ftell function returns the current position within the file. 



lseek, ftell, rewind. 


FSEL INPUT 


GEM AES 


ret = fsel_input(directory,fi le_name,&ok); 
int ret; 
short ok; 

char *di rectory, *f i Le_name; 

This function makes the file selector appear on the screen, lets the operator 
use it and returns the value selected. 

path is a string containing the drive and directory. This is updated when the 
function returns. 

On input, f i le_name is the name of the default file, on exit it is the value 
that the user has entered; it should be at least 13 bytes long. 

ok is returned as 1 if the user clicks on OK or 0 if on Cancel. 

ret is 0 if an error occurred and 1 if there was no error. 
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SO This function displays the file selector and stores in whole_name the 
entire name of the file selected (the path + the name) and returns 1 if the 
name is valid and 0 otherwise. 

The path and file names are, by default, preserved between successive calls to 
the function, so that if the user changes drive or folder, the file selector will 
display those that the user has previously selected. 


char pa t h_name C70D = fit e_name [ 1 2H = 

char who l e_nameC 80 D ; 
int ask_f or_name ( ) 

short ok_c licked; 
char * p ; 
int ok; 
ok = 0; 

if ( f se l_i npu t ( pa t h_name, f i l e_name , &ok_c L i c ked ) && ok_clicked) 
{ 

st rcpy C who L e_name, path_name); 
if (p = strrchrC whole_name, ' \ \ ' ) ) 
i 

strcpy(p+1, file_name); 
ok = 1 ; 

> 

> 

return(ok); / * 1 if name ok, 0 otherwise * / 

> 


FSETDTA 


GEMDOS 


Fgetdta(buffer); 
char * b u f f e r ; 

Set the GEMDOS data transfer address as used by the file search functions. 


FSFIRST 


GEMDOS 


ret = F s f i r s t ( f i l e_s p e c , attributes); 
int ret, attributes; 
char * f i L e_s pec; 

Searches for the first file matching the f i le_spec with the corresponding 
attributes (see Fattrib). The f i le_spec may contain the wildcards * and 


If a file is found, the function returns 0 and the GEMDOS data transfer area 
(found using dta = FgetdtaO) contains the following information: 


dtaC21 D 

file attributes 

d t a C 2 2 5 and d t a C 2 3 3 

time stamp 

d t a C 2 4 ] and d t a C 2 5 H 

date stamp 

d t a C 2 6 3 to d t a C 2 9 1 

file size 

d t a C 3 0 j onwards 

file name 
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FSNEXT 


GEMDOS 


ret = FsnextC); 
i n t ret; 

Searches for the next file satisfying the conditions given by Fsf i rst. This 
function must not be called without calling f s f i r s t . 

This function returns 0 if a file is found and the information found is stored 
in the GEMDOS d t a . See F s f i rst. 


FTELL 


ANSI 


//include <stdio.h> 
pos = ftell(fp) 
i n t pos; 

FILE * f p ; 

Returns the position in the file f p of the next byte that will be read or 
written. 



This position may be modified by using f s e e k . 


FWRITE 


ANSI 


//include <stdio.h> 

i tems_wri tten = fwriteCbuffer, item_size, n, fp); 
int i tems_wri tten, n, item_size; 
char * b u f f e r ; 

FILE * f p ; 

Writes n items of size i tem_si ze bytes to the file given by f p. The file must 
have been opened for write using fopen. 

The items are written until n items have been written or an error occurs. 

buffer is the buffer where the items to write are read from. 

The function returns the number of entire items written as its result. If this 
number is less than n then an error has occurred. 



fputs, fputc, ferror, errno. 
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GEMDOS 


FWRITE 


bytes_wri tten = Fwri te( f handle, no_bytes, addr); 
int bytes_wri tten, no_bytes, fhandle; 
char * a d d r ; 

Writes n o_b ytes from the buffer at addr to the file given by fhandle. 




This function returns the number of bytes actually written. After an error, 
this will be less than no_bytes. 


GEMDOS 


GEMDOS 


ret = gemdosCno, a r g 1 , a r g 2 . . . ) ; 

int no, result; 

long argl ,arg2,arg2 . . . 

Call a GEMDOS function. 


is the function to call. 


a rg 1 ,a rg2 . . . 


are the parameters for this particular function. 




A 


GEMDOS functions may be called directly using their names. For 
example CconinO is equivalent to gemdosd). 


V 

/ * o bios, xbios. 


C 

GETBPB 

GEMDOS 




bpb = Ge t bpb ( d r i ve_no ) ; 
short * b p b ; 
int dri ve_no; 

Returns a pointer to the Bios Parameter Block (bpb) for the disk drive given 
by drive_no (0=A, 1=B,...). 

GETC 

UNIX 


Equivalent to f g e t c . 



GETCHAR 

UNIX 


Equivalent to fgetchar. 
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GETCWD 


UNIX 


path = getcwdCp, length); 
char * p a t h , * p ; 

int length; 

This function returns the current directory for the current drive. 

If the pointer p is not zero then the name of the directory is placed in the 
buffer pointed to by p and p is returned as the result of the function. 

If p is zero, a block of memory of length bytes is allocated using malloc and 
the name is stored there. The value returned by the function is a pointer to 
this block. 

The value returned is therefore always a pointer to the current path or is 0 if 
an error has occurred. In this case the variable errno will specify the error. 


A 


If the parameter p is zero the program should ensure that it returns the 
memory allocated by the implicit call to malloc by using the free function. 



Dgetpath, errno. 


IGETMPB 


GEMDOS 


Getmpb(buffer); 
char *buf f er; 
int bytes; 

Returns a pointer to the Memory Parameter Block used by the system. 


GETS 


ANSI 


p = gets(buffer); 
char *p,*buffer; 

Reads a string of characters from the standard input file, stdin, which is the 
keyboard by default. 

Characters are read into buffer until a Return character is found. This isn’t 
placed in the buffer but a null character \0 is placed instead. 

The value returned is equal to buffer. 
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A 


This function doesn’t make any checks that the buffer hasn’t 
overflowed. We therefore recommend that you use fgetsCbuf fer, max, 
stdin) which will stop if you enter max characters before a carriage return. 








a 


fgets, fgetchar. 


IGETSHIFT 


GEMDOS 


ret = Getshift(keys); 
int ret, keys; 

Activate some control keys if keys>=0 or read which keys are pressed if 
key s=-l . The value returned is always the new current state of the keys. 

The keys are given as a bit map as follows: 


0 

Right Shift | 

1 

Left Shift 

2 

Control Key 

3 

Alternate Key 

4 

Caps lock 

5 

Clr/Home 

6 

Insert 




GETREZ 


GEMDOS 


N 


resolution = GetrezC); 
int resolution; 

Returns the current screen resolution 2=high, l=medium, O=low. 


GETTIME 


GEMDOS 




date_ti me = GettimeC); 

Long d a t e_t i me ; 

Returns the date and time as a long integer in the same format as for the 
functions Tgetdate and Tgettime. 


v_ 
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GEMDOS 


GIACCESS 


vaL = GiaccessCvalue, register_no); 
int val, value, register_no; 

Reads or writes a value from/to a given sound chip register. 

For reading pass the register number in register_no; to write the register 
number plus 128. 

The value returned is the value read or written. 


GRAF DRAGBOX GEM AES 


ret = g r a f _d r a g b o x ( w i d t h , height, 
x_i nit, y_i nit, 

x_limit, y_l i mi t , w_l i mi t , h_limit, 

8x_end, &y_end); 
int width, height, x_ in it,y_init; 
int x_l i m i t , y_l i m i t , w_l i m i t , h_l i m i t ; 
short x_end, y_end; 

Displays an outlined rectangle (with initial co-ordinates x_init, y_i nit) of 
the specified width and height. The user may then move the rectangle with 
the mouse until the mouse button state changes. The box is forced to remain 
inside the rectangle given by x_l i mi t, y_l i mi t , w_l i mi t , h_l imi t. 

The final position of the rectangle is returned in x_end and y_end. 


GRAF GROWBOX GEM AES 


ret = g ra f_g rowbox ( xl ,y1 , wl , h 1 , x2,y2,w2,h2); 

int x1,y1,w1,h1; 
int x2,y2,w2,h2; 

Draws an expanding rectangle in the same way as when a window is opened 
using the Desktop, xl.yl.wl, hi specify the smaller rectangle and 
x2,y2,w2,h2 the larger one. 

The result of the function is 0 if an error occurs. 


GRAF HANDLE GEM AES 


vdi_handle = g r a f _h a n d l e ( & c h a r_w i d t h , 8 c h a r_h e i g h t , 

8box_width, 8box_height); 
int vdi_handle; 

short c h a r_w i d t h , c h a r_h e i g h t ; 
short bo x_w i d t h , bo x_h e i g h t ; 

Returns the VDI virtual workstation that the AES is using and also the size of 
a character cell and the size of a boxed character. 
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GRAF_MKSTATE GEM AES 


v_ 


g r a f _m kstate(&x,&y,&button,&keyboard); 
short x , y , button, keyboard ; 

Returns the current position of the mouse (x,y), the state of the mouse 
buttons (button) and the state of the shift keys (keyboard). 







evnt_button. 


GRAF MOUSE GEM AES 


ret = g r a f _mo u s e ( mou s e_f o rm , a d r ) ; 
int re t , mouse_f orm; 
char * a d r ; 

Changes the mouse form. 




GRAF_MOVEBOX GEM AES 






ret = g r a f _mo v e b o x ( w i d t h , height, 

x_source, y_source. x_dest, y_dest); 
int ret, width, height; 

int x_source,y_source, x_dest, y_dest; 

Displays a box of size (width.height) moving between the two points 
(x_sou r c e,y_sou r c e) and (x_dest,y_dest). 


GRAF_RUBBERBOX GEM AES 


re t = graf_rubberbox(x,y, min_width, min_height, 

& w i d t h , Sheight); 

\ int ret, x , y ; 

int min_width, m i n_h e i g h t ; 
short width, height; 

Displays an outline box from (x.y) to the current mouse position and lets the 
user change the size of the box without letting it become smaller than 
min_width, min_height. When the user releases the mouse the current 
width and height are returned in the variables width and height. 
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GRAF_SHRINKBOX GEM AES 


ret = g r a f _s h r i n k b o x ( x 1 , y 1 , w 1 , h 1 , x2,y2,w2,h2); 

int x1,y1,w1,h1; 
int x2,y2,w2,h2; 

Draws a rectangle shrinking in the same way as when you close one of the 
Desktop’s windows, xl.yl.wl.hl specifies the smaller rectangle and 
x2,y2,w2,h2 the larger one. 


r e t is zero unless there was an error. 


GRAF SLIDEBOX 

GEM AES 

//include <gemlib.h> 

chi Id, 

position = g ra f_s l i debox ( t ree.adr, parent, 
vertical); 

int position, parent, child, vertical; 


OBJECT *tree_adr; 


Lets a child object slide within its parent. 


GRAF WATCHBOX 

GEM AES 


//include <gemlib.h> 

position = g ra f_wa t c h box ( tree_adr, object_no, 
i n_s t a t e , out_state); < 

int position, object_no, in_state, out_state; 

OBJECT *tree_adr; 

Changes an object’s state as the mouse moves inside or outside of the object 
until the mouse button is released. This should only be called when the 
mouse button is down. 

The value returned (position) indicates if the mouse is within the object 
(1) or outside it (0) when the mouse button is released. 

GTEXT BOX HiSoft C 


object no = gtext box ( box no, x,y, text, 

char_size, border, fill); 

int o b j e c t__n o , box_no, x, y, char_size, border, fill; 
char * t e x t ; 

Adds a graphics text item to a dialog box. 



Section 3.3.10, Help command (gtext_bo). 
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V_ 


Vw. 


v^ 




v_ 

c 



L 

L 


IABS 

ANSI 

ret = iabs(val); 
int ret,val; 


This function returns the absolute value of its parameter. Both values are of 
type integer. 

abs, labs, fabs. 


IKBDWS 

GEMDOS 

IkbdwsClen, byte_string); 
int l e n ; 

char *by t e_s t r i ng; 


Writes a string of ten bytes from byte_string to the keyboard processor. 

INIT.BOX 

HiSoft C 

box_no = i n i t_box ( w i d t h , height, objects); 
int box_.no, width, height, objects; 


Creates and initialises a dialog box. 


/^S Section 3.3.3, Help command (init_box). 


INIT.MENU 

HiSoft C 

entry_info = i n i t_me n u ( d e s k_n a m e , file_name, 
elements); 

int entry_info, titles, elements ; 
char *desk_name, *name_info; 

titles. 

Initialises a menu. 


Section 3.4.2, Help command (init_box). 
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INITMOUS 


GEMDOS 


ret = InitmousCtype, param, 0); 
i n t ret, type; 
char *param; 

Initialise the mouse depending on the type of the parameter: 


6 

disable the mouse 

l 

enable mouse in relative mode 

2 

enable mouse in absolute mode 

4 

enable mode in keyboard mode 


param is a pointer to a parameter block: 


pa ramCO] 

gives the origin of y co-ordintates: 
l=top O=bottom 

paramCI D 

is a parameter to the keyboard’s set 
mouse button command 

paramC2] 

is the horizontal mouse scale 

pa ramC3] 

vertical mouse scale 

p a r a m C 4 and 5 1 

maximum horizontal mouse position 

p a r a m C 6 and 7 1 

maximum vertical mouse position 

p a r a m C 8 and 9 D 

initial horizontal mouse position 

paramCIO and 1 1 1 

initial vertical mouse position 


IOREC GEMDOS 


buf f er_adr = Iorec(device); 

int device; 

char *buffe r_a dr; 

Returns the address of the i/o buffer for a device (0=RS232, l=keyboard, 
2=MIDI). 
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IS 





ANSI 

ret 


isalnum(c); 

/* 

alphanumeric character */ 


ret 

= 

isalpha(c); 

/* 

alphabetic character */ 


ret 

= 

isascii(c); 

/* 

ASCII character ( < 1 28) */ 


ret 

= 

iscntrl(c); 

/* 

Control character (<32) */ 


ret 

= 

iscsym(c); 

/* 

C identifier character * / 


ret 

= 

iscsymf(c); 

/* 

initial C identifier character */ 

ret 

= 

isdigit(c); 

/* 

decimal digit * / 


ret 

= 

isgraph(c); 

/* 

graphics character */ 


ret 

= 

islower(c); 

/* 

lower case letter */ 


ret 

= 

isprint(c); 

/* 

printable character * / 


ret 

= 

ispunct(c); 

/* 

punctuation character */ 


ret 

= 

isspace(c); 

/* 

space, tab or \n */ 


ret 

= 

isupper(c); 

/* 

upper case letter */ 


ret 

= 

isxdigit(c); 

/* 

hexadecimal digit * / 


i n t 

ret, c ; 





These functions test the value of a character c and return either (0= 
or 1 =TRUE) if the character satisfies a certain condition. 


FALSE 


For example islower('e') returns 1 because 
isupperCe') returns 0. 


e is a lower case letter and 


ITEM MENU 


HiSoft C 




entry_no = i t e m_m e n u ( t i t l e ) ; 
i n t e n t ry_no; 
char * t i 1 1 e ; 

Adds an entry to a menu. 



JDISINT 

GEMDOS 


ret = J d i s i n t ( i n t_n o ) ; 
int ret, int_no; 


c 

Disables interrupt int_no of the 68901. 



JENABINT 

GEMDOS 

v - 

ret = Jenabint(int_no); 
int r e t , i n t_n o ; 

Enables the 68901 interrupt number int_no. 





c 
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KBDVBASE 


GEMDOS 


descri ptor_adr = KbdvbaseC); 
char *descriptor_adr; 

Returns the address of the keyboard vector table. 


GEMDOS 


KBRATE 


period = KbrateCdeLayl, d e L a y 2 ) ; 

Long period; 

int d e L a y 1 , d e L a y 2 ; 

Sets or returns the keyboard repeat rate, d e l a y 1 is the delay before key 
repeat and d e L a y 2 after. 

If both parameters are -1 then the current settings are not changed. 

The function returns a long composed of the new values of d e L a y 1 and 
de Lay2. 


GEMDOS 


KEYTBL 


old_address = KeytbLCunshift, shift, capsLock); 
char * o L d_a d d r e s s , unshift, shift, capsLock. 

Sets the BIOS keyboard translation tables. 


LABS 


ANSI 


ret = Labs(val); 

Long ret,vaL; 

This function returns the absolute value of its parameter. Both values are of 
type Long. 



abs, iabs, fabs. 
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LDEXP 


ANSI 


a=Ldexp(b / exp); 
double a,b; 
i n t exp; 

Produces a floating point number from a mantissa b (0.5< = b<l) and 
exponent exp. This is the inverse operation to f rexp. 

The following relation is true: 

a = b * (2 A exp) 



frexp. 


LINEA 


HiSoft C 

//include <linea.h> 
param_adr = lineaOC) 

; /* 

return address of LineA 

v a r s * / 

lineal (); 

/* 

draw a point */ 


linea2(); 

/* 

read colour of a point 

*/ 

l i n e a 3 ( ) ; 

/* 

draw a line * / 


l i n e a A ( ) ; 

/* 

draw a horizontal line 

*/ 

l i n e a 5 ( ) ; 

/* 

draw a filled rectangle 

*/ 

l i n e a 6 ( ) ; 

/* 

draw part of a polygon 

*/ 

linea7(blk); 

/* 

bit blk operations */ 


l i n e a 8 ( ) ; 

/* 

write a character */ 


l i n e a 9 ( ) ; 

/* 

show mouse */ 


lineaaO; 

/* 

hide mouse */ 


lineabO; 

/* 

change mouse form */ 


lineac(save); 

/* 

undraw sprite */ 


linead(x, y , sprite. 

save); / * draw sprite * / 


lineaeO; 

/* 

copy raster form */ 


LineafC); 

/* 

seed fill * / 


LA_INIT *param_adr; 

/* 

Pointer to LineA variables */ 

L A_S P R I T E *sprite, * 

save; 

/* Pointers to Sprites 

*/ 

i n t x , y ; 

/* 

Sprite co-ordinates */ 


char *blk; 

/* 

Pointer to a bitblk structure */ 


Library Reference 


HiSoft C 


Page 207 


The following three structures are used when calling the LineA routines. 
They are defined in the linea.h file. 

typedef struct La_vari abLes 


short 

l a_p lanes; 

/* 

short 

l a_w i d t h ; 

/* 

short 

*la_contrl; 

/* 

short 

* la_i n t i n; 

/* 

short 

* la_pt si n; 

/* 

short 

* La_i n tou t ; 

/* 

short 

*la_ptsout; 

/* 

short 

la_col0bi t; 

/* 

short 

la_co l 1 bi t ; 

/* 

short 

la_co 1 2 b i t; 

/* 

short 

la_co l 3bi t ; 

/* 

short 

la_lst l i n; 

/* 

short 

l a_ Inmask; 

/* 

short 

la_wmode; 

/* 

shor t 

La x 1 ; 

/* 

short 

la_y1; 

/* 

short 

la_x2; 

/* 

short 

la_y2; 

/* 

short 

* la_pa tpt r; 

/* 

short 

la_pa tmsk; 

/* 

short 

la_mf i l l ; 

/* 

short 

la_c lip; 

/* 

short 

la_xmi nc l ; 

/* 

short 

la_ymi nc l ; 

/* 

short 

la_xmaxc l; 

/* 

short 

la_ymaxcl; 

/* 

short 

la_xdda; 

/* 

short 

la_dda i nc; 

/* 

short 

la_sca Ldi r; 

/* 

short 

l a_mono; 

/* 

short 

la_xsource; 

/* 

short 

la_y source; 

/* 

short 

l a_d s t x ; 

/* 

short 

la_ds ty; 

/* 

short 

l a_d e l x ; 

/* 

short 

la_de ly; 

/* 

short 

* la_f base; 

/* 

short 

l a_f w i d t h ; 

/* 

short 

l a_s ty l e; 

/* 

short 

la_litemask; 

/* 

short 

l a_s ke wma s k; 

/* 

short 

l a_w i e g h t ; 

/* 

short 

la_rof f ; 

/* 

short 

l a_lof f ; 

/* 

short 

la_sca le; 

/* 

short 

la_chup; 

/* 

short 

la_tex t f g; 

/* 

short 

* la_sc r t chp; 

/* 

short 

la_scrpt2 

/* 

short 

la_textbg; 

/* 

short 

la_copy t ran; 

/* 

> L A__V ARIABLES; 



n */ 


0 */ 


is plotted*/ 


colour for plane 2 */ 
colour for plane 3 */ 
whether last line point 


xl coord */ 


fill pattern mask */ 


x clipping value */ 
y clipping value * / 
x clipping value */ 
y clipping value*/ 


x co-ord of char in font form */ 
y co-ord of char in font form */ 
x co-ord of character on screen*/ 
y coord y of character on screen */ 


* pointer to font base */ 


text*/ 


*/ 
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typedef struct la_init 


struct la__variabl.es *la_aO; 




/* 

pointer 

to 

the LA. 

-VARIABLES area */ 

long 

l a_a 1 ; 

/* 

poi nter 

to 

system 

font header list */ 

long 

> LA INIT; 

l a_a 2 ; 

/* 

pointer 

to 

Li neA 

routines */ 


typedef struct la_ sprite 



short 

ta. 

_xhot; 

/* 

x offset of 

sprite hot 

spot 

*/ 


short 

la. 

_y h o t ; 

/* 

y offset of 

sprite hot 

spot 

*/ 


short 

la. 

-format; 

/* 

1 for VDI, 

-1 for X0R 

*/ 



short 

la. 

_c o 1 1 ; 

/* 

background 

colour */ 




short 

la. 

_c o 1 2 ; 

/* 

foreground 

colour */ 




short 

la. 

_imageC323; 

/* 

sprite image */ 




/♦(words of mask & data alternate) */ 

>LA_SPRITE; 



tii nc lude <1 i nea . h> 

LA_I NIT * p t r ; 

LA_VARI ABLES *p; 
void mainO 

ptr = lineaOC); 

/* make p contain the address of the LineA variables*/ 
p = ptr->la_aO; 

/* draw a point */ 

( p-> la_pt si n ) CO] = 100; 

( p-> la_p t s i n ) C 1 U = 50; 

( p-> la_i n t i n ) COO = 1; 
lineal (); 

/* draw a line */ 
p->la_x1 = 105; 
p->la_y1 = 55; 
p->la_x2 = 305; 
p->la_y2 = 105; 
p-> la_co LObi t = 1; 
l i nea3( ) ; 

/* draw a rectangle */ 
p->la_x1 = 300; 
p->la_y1 = 60; 
p->la_x2 = 400; 
p->la_y2 = 120; 
linea5(); 

> 


LOG 


ANSI 


a = log(b); 
double a, b; 

Returns the natural log (to base e) of the argument. Both values are double 
reals. 
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ANSI 


LOG 10 


a = LoglOCb); 
double a, b; 

Returns the log to base 10 of the argument. Both values are double reals. 

LOGBASE GEMDOS 


scr_addr = LogbaseC); 
char *scr_addr; 

Returns the address of the logical screen (that which software routines 
modify). 


LQSORT 


ANSI 


L q s o r t ( a r r , n ) ; 
long *arr; 
i n t n ; 

This function sorts an array arr of long integers into ascending order. 



dqsort, sqsort, tqsort. 


LSEEK 


UNIX 


ret = IseekCfd, pos, mode); 
int ret, fd, pos, mode; 

Moves the input/output position on the UNIX file f d depending on the value 
of mode: 


0 

pos gives the number of bytes from the start of the file j 

1 

pos gives the number of bytes from the current 
position 

2 

pos gives the number of bytes from the end of the file 
(this number must always be 0 or negative) 


The value returned by the function is 0 if the operation was successful or 
non-zero if an error occurred in which case errno indicates the type of 
error. 
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k^ 


When mo d e=2, the number of bytes must be negative to move to before 
the end of the file. It is not possible to position past the end of file. 

This function returns the new position from the beginning of the file. 

This function may be used to find the length of a file, as follows: 

Length = LseekCfd, 0, 2); 

fseek. 

MALLOC 






( 


k^ 

c 

k^ 

k_ 


adr = maLLoc(size); 
char * a d r ; 
unsigned Long size; 

Allocates a block of memory of the size that is passed as a parameter. 

The value returned is a pointer to the allocated memory or zero if the 
allocation was not possible. 

The memory is allocated from GEMDOS system memory whose size is fixed 
when the interpreter is loaded. This can be changed if you have sufficient 
memory. 



Section 1.4.13, Malloc, Mfree, calloc, free, realloc. 


MALLOC 


GEMDOS 






L 


adr = MaLLoc(size); 
char *adr; 
unsigned Long size; 

Allocates a block of memory whose size is passed as a parameter. 

The value returned is a pointer to the allocated memory or 0 if the allocation 
was not possible. 

This function returns the number of free bytes if the value passed is - 1 . 



malloc 
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MATHERR 


UNIX 


//include <math.h> 

ret = matherr(mathstr); 
i n t ret; 

struct exception *mathstr; 

This function is called when an error occurs during the execution of a 
mathematical function. The details of the error are stored in the mathstr 
structure which is modified by the function. 


MAX ANSI 


larger = m a x ( a , b); 

int a, b , larger; 

This function returns the larger of the two integers passed as parameters. 


MEDIACH 


GEMDOS 


test = M e d i a c h ( d r i v e_no ) ; 
int test, driv e_n o ; 

Tests if the floppy disk has been changed in drive A (drive_no = 0) or drive B 
(driv e_n o = 1 ). 

The value returned is: 


0 

the disk has not changed 

1 

the disk may have changed 

2 

the disk has changed 


MEMCCPY 


UNIX 


p = memccpyCdest, source, ch, bytes); 

int bytes, h; 

char * d e s t , *source, * p ; 

This function copies a block of memory from source to dest. 
bytes gives the number of bytes to copy. 

The copy stops when the number of bytes has been copied or the character 
ch is found. 

The value returned is a pointer and has the same value as dest. 



memcpy, strcpy, stmcpy. 
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MEMCHR 

UNIX 

pos = memchrCblock, ch, bytes); 
int ch, bytes; 



char *block, *pos; 

This function returns a pointer to the first character c h found in the block 
starting at block and of length bytes. 

If the character cannot be found 0 is returned. 


strchr, strrchr. 


IMEMCMP 

UNIX 

comp = memcmpCblockl, block2, bytes); 
char * b l o c k 1 , * b l o c k 2 ; 



int comp, bytes; 

This function compares two blocks, blockl and block2, of length bytes. 

If the value returned is 0 then the two blocks are identical. 

If not, the comparison stops as soon as two bytes differ and the value 
returned is positive or negative depending on whether the character from 
the first block is larger or smaller than the second respectively. 


/^S strncmp. 


MEMSET 

UNIX 

p = memsetCbuf, ch, len); 
char *buf, * p ; 



int len, ch; 

This function fills a block of memory pointed to by buf and l e n bytes long. 
The value returned is a pointer to the same place as buf. 


MEMCPY 

UNIX 

dest = memcpy (dest, source, len); 
int len; 

char *dest, ^source; 



This function copies a block of len bytes from source to dest. The value 
returned is dest. 

The areas to be copied may partially overlap. 
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MENU BAR 


GEM AES 


# include <gemlib.h> 

ret = menu_bar(menu_adr, display); 
int ret, display; 

OBJECT *men u_a dr; 

Displays (d i s p l a y = 1 ) or deletes (d i s p l a y = 0) the menu bar given by 
men u_a d r . 

The value returned is 0 following an error. 


MENU ICHECK GEM AES 


//include <gemlib.h> 

ret = me n u_i c h e c k ( me n u_a d r , entry_.no, check); 
int ret, entry_.no, check; 

OBJECT *menu_adr; 

Displays (check = l) or removes (check = 0) a tick in front of menu entry 
entry_no within the tree menu_adr. 

The value returned is 0 following an error. 


MENU IENABLE GEM AES 


//include <gemlib.h> 

ret = m e n u_i e n a b l e ( me nu_a d r , entry_.no, enable); 
int ret, entry_no, active; 

OBJECT *menu_adr; 

Enables (enable = l) or disables (enable=0) entry number entry_no from 
menu tree menu_adr. Disabled menus are displayed in grey. 

The value returned is 0 following an error. 


MENU REGISTER GEM AES 


entry_no = me n u_r e g i s t e r ( a p p l_i d , entry_name); 
int a p p L_i d , entry_no; 
char *entry_name; 

Adds the name of a desk accessory within name entry_name and application 
id a p p l_i d to the desk menu. The a p p l_i d is returned by a p p l_i n i t . 

The value returned is the entry number within the desk menu. 
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MENU.TEXT 

GEM AES 


//include <gemlib.h> 

ret = men u_t ext (menu_adr, entry.no, string); 
int ret, entry.no; 
char * s t r i n g ; 

OBJECT *menu_adr; 

Changes the text for the menu entry entry.no of tree menu.adr to be 
string. 

The value returned is zero if an error occurred. 


MENU.TNORMAL 

GEM AES 

//include <gemlib.h> 



ret = menu.tnormaKmenu.adr, title.no, inverse); 
int ret, title_.no, inverse; 

OBJECT *men u.a dr; 

Displays a menu title in inverse video (inverse = 1) or normal (inverse = 0). 
The menu title is given by titte_no and the tree address menu.adr. 

The value returned is 0 following an error. 


MFPINT 

HfpintCvector.no, a d r ) ; 
int v e c t o r_n o ; 
char * a d r ; 

Sets interrupt vector vecto r_n o to be a d r . 

GEMDOS 

MFREE 

GEMDOS 

ret = Mfree(pointer); 

int ret; 

char ^pointer; 



Frees the memory array given by pointer which has been allocated by 

M a l l o c . 

This function returns zero if successful. 
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MIDIWS 

GEMDOS 

Mi di ws( Len, str); 
i n t l e n ; 
char * s t r ; 


Sends a string of l e n characters given by s t r to the MIDI port. 

MIN 

ANSI 

smaller = min(a, b); 
int a, b , smaller; 


Returns the smaller of two whole numbers a and b. 


MKDIR 

UNIX 

ret = mkdi r ( d i re c t o ry_name ) ; 
int ret; 

char *di rector y_n a me; 


Creates a new directory called d i rectory_name. 


The value returned is 0 if successful; if the operation fails 
errno will indicate the source of the error. 

-1 is returned and 

Dcreate, errno. 


MODF 

ANSI 

f rac = modf(dbl, Swhole); 
double whole, dbl, frac; 


Splits a double floating point number into its whole (returned in whole) and 
fractional part (returned as the result of the function). 

Of course. 


dbl = whole + f rac; 


/^S fmod, frexp. Id exp. 
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MOUSE 


ANSI 


status = mouse(8x, &y, button_no); 
int x,y, status, button_no; 

Reads the position of the mouse into (x ,y) after the user has clicked a button. 

If b u 1 1 o n_n o = 0 then the function doesn’t wait for a click but returns the 
mouse position immediately. 

If b u 1 1 o n_n o = 1 then mouse waits for a click on the left button. 2 the right 
button, 3 both buttons at once. 

The value returned gives the state of the button in the same form as for the 
parameter button_no. 



Help command, mouse. 


GEMDOS 


MSHRINK 


ret = Ms h ri n k ( ba s e_pa g e , bytes); 
int ret, bytes; 
char *bas e_pa g e ; 

Free memory to system during initialisation. 

base_page is the program’s base page; bytes is the number of bytes to 
return. 

The value returned by the function is zero if the operation was successful. 


OBJC ADD 


GEM AES 


^include <gemlib.h> 

ret = objc_add(tree_adr, parent_obj, add_obj); 
int ret, parent_obj, add_obj; 

OBJECT *tree_adr; 

Adds an object (of index add_obj) to have parent parent _obj in the tree 
t re e_a d r . 

The value returned is 0 if an error occurs. 
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OBJC CHANGE GEM AES 


^include <gemlib.h> 

ret = ob j c_change ( t ree.adr, object_no, 0, x, y, w, h, 
object_state, d r a w_o b j e c t ) ; 
int ret,ob j ect_no; 
int x, y , w , h; 

int ob j ec t_sta t e, draw_object; 

OBJECT * t r e e_a dr ; 

Changes the state of the object ob j ect_no in the tree tree_adr to be 
ob ject_state. If draw_ob ject =1 then re-draw the object with the 
rectangle (x,y,w,h). 

The value returned is 0 if an error occurs. 


OBJC DELETE 


^include <gemlib.h> 

ret = ob j c_d e L e t e ( t r e e_a d r , object_no); 
int ret, object_no; 

OBJECT * t r e e_a dr; 

Removes the object object_.no from the tree tree_adr. 


OBJC DRAW GEM AES 


^include <gemlib.h> 

ret = ob j c_d r a w ( t r e e_a d r , object_no. Level, x, y, w, h); 
int ret, object_no, level; 
int x, y, w, h; 

OBJECT * tree_adr; 

Draws an object (ob ject_no) in a tree (tree_adr) within the clipping 
rectangle (x,y,w,h). 

If l eve 1 = 0 then the function draws just the object itself. 

If l eve 1 = 1 then the function draws the object and its children. 

If l eve l = 2 then the object, its children and grand children are drawn. 

The maximum level is level 10. 

Zero is returned if there was an error. 


GEM AES 
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OBJC EDIT 


GEM AES 


//include <gemlib.h> 

ret = o b j c_e d i t ( t r e e_a d r , object_no, character, position, 
kind, &ret_position); 

int ret, object_no, character, position, kind; 
short ret_posi tion; 

OBJECT * tree_adr; 

Display a character in a G_FTEXT object (given as object_.no of the tree 
tre e_a d r). 

position gives the index where the character is to be added. The position 
after the addition is given as ret_position. 


The operation performed depends on the value of kind: 



i 0 

E D_S T A R T 

reserved 


| 1 

E D _ I N I T 

display the string and turn the text cursor on 


1 2 

E D _ C H A R 

validate the character and re-display string 


i 3 

E D _ E N D 

turn text cursor off 

The value returned is zero if an error occurred. 

OBJC_FIND 

» GEM AES 


# include <gemlib.h> 

object_found = o b j c_f i n d ( t r e e_a d r , object_.no, level, x, y); 
int object_no, level, object_found ; 
int x , y ; 

OBJECT * tre e_a dr; 

Finds which object is under co-ordinates (x, y). 

The search is within tree tree_adr starting at object object.no (normally 
0). The search descends to a level given by level (see objc_draw). 

The value returned is -1 if the object is not found; otherwise it is the index of 
the object that has been found. 


OBJC OFFSET GEM AES 


//include <gemlib.h> 

ret = ob j c_of f set ( tree_adr, object_no, &x, &y); 

int ret, object_no; 
short x, y; 

OBJECT * tree_adr; 

Returns the co-ordinates of object_no of tree tree_adr in (x, y). 
The value return is zero if an error occurs. 
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OB JC ORDER GEM AES 


//include <gemlib.h> 

ret = objc_of fset(tree_adr, object_no, new_position); 
int ret, objec t_n o , n e w_p o s i t i o n ; 

OBJECT * tree_adr; 

Moves an object (object_no) from tree tree_adr within the tree structure. 
The value new.position (0,1,2...) indicates which child (first, second, 
third) of its parent the new object is to be. 

The value return is zero if an error occurs. 


OFFGIBIT 


GEMDOS 


Offgibit(bit_no); 
int b i t_n o ; 

Resets (to 0) a bit of port A of the sound chip. Which bit to zero is passed as a 
parameter. 


ONGIBIT 


GEMDOS 


Ongi bi t (bi t_no); 
int b i t_n o ; 

Sets (to 1) a bit of port A of the sound chip. Which bit to set is passed as a 
parameter. 


OPEN 


UNIX 


//include <fcntl.h> 

nf = open(file_name, mode, access); 

char *file_name; 

int nf, mode, access; 

This function opens a file file_name and returns its file handle, mode 
indicates how the file is to be opened as given in the following table. These 
constants are defined in the file fcntl.h): 


0_R DON LY 

read only 

0_W RO N L Y 

write only 

0_R D W R 

read and write 

0_ A P P E N D 

write starting at the end of the file 

0_T RUN C 

if the file exists, delete it 

0 _ C R E A T 

if the file doesn’t exist create it 

0 _ E X C L 

(used oniy with o_Creat) if the file exists 
don't open it 
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The values above can be combined using the OR operator e.g. 
0_C R E A T I 0_E X C L . 

The access parameter specifies how the file may be accessed and takes one 
of the following values: 

access = S_l read : file is read only. 

access = S_i R E A d | s_i w R I T E or mo d e = 0 : file is open for read/write. 

The value returned by the function is the file number which must be used for 
all input-output operations on the file. 

If an error occurs, this function returns -1. The variable errno indicates 
which error has occurred. 




When you open a file with this function, you can only use the Unix 
input/output functions (read and write for example) and not the ANSI ones 
(e.g. tread, f write, fprintf). 



creat, chmod, close, fopen, errno. 


OPEN WINDOW HiSoft C 


window_no = open_wi ndow(at tr i butes, x, y, w, h, title, 
comment); 

int window_no, attributes, x, y, w, h; 
char * t i t l e , *comment; 

Opens a window. 



Section 3.2.3, Help command (open_win). 


PEXEC 


GEMDOS 


base_page = PexecCexecute, p r o g r a m_n a m e , arg_list, 
envi ronment); 
char *ba s e_pa g e ; 
int execute; 

char *program_name, *arg_list, *envi ronment; 

Load and/or execute a program in memory. 

If execute =0, the program is loaded but not executed. If execute =3, the 
program is loaded and executed. 

progra m_n a m e is the name of the program to load. arg_li st gives the 
arguments that you wish to pass onto the program, environment gives the 
environment variables to be passed. 

The function returns the address of the base page of the program that has 
been loaded. 
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PHYSBASE 


GEMDOSl 


screen_adr = PhysbaseO; 
char *screen_adr; 

Returns the address of the physical screen (that which is actually displayed 
on the monitor). 


POS WINDOW HiSoft C 


pos_w indowCwi ndow_.no, column, row); 
int window_no, column, row; 

Positions the text cursor within a window that has been opened by 
ope n_w i n d o w . 



Section 3.2.7, Help command (pos_wind). 


POW 


ANSI 


result = powCnumber, exponent); 
double result, number, exponent; 

Raise the parameter number to the power of exponent. 

The two parameters and the value returned are both double reals. 

The three values satisfy: 

results number A exponent. 



log, log 10, exp. 
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PRINTF 


ANSI 


Length = printfC format, argl , a r g 2 , . . . ) ; 
char ^format; 
int Length; 

???? argl, arg2, ... 

This function performs formatted output. The output is to the standard file 
stdout (the screen, by default). 

The p r i n t f function builds up its output based on a control string and then 
sends it to the screen by default. The value returned by this function is the 
number of characters output by p r i n t f . 

The parameter format contains both ordinary characters to be simply 
copied to the screen and format conversion characters with which to write 
the other arguments to the pri ntf function. 

Each one of these conversion sequences outputs a string of characters that is 
not explicitly contained in the format string. 

???? indicates that the parameters may be of different types. 

You must have an exact correspondence between the control string and the 
parameters argl, arg2, ... Each conversion specification is associated with 
one parameter that describes how that parameter is to be written to the 
screen. 

The type of the variable indicated in the specification must correspond 
exactly with the type of the variable that is passed as a parameter. Otherwise, 
the results are not predictable... 

The conversion specifications are of the form: 

Uattributes][minimum][.precision][L]type 

A specification always starts with the character %. There then follows various 
elements in the following order. 

1. An optional attributes field which can contain 0 or more of the following 
characters: 



A minus sign indicates that the value converted is left 
justified within the output field specified. Right 
justification is used by default. This attribute does not 
have a visible effect on the display unless you specify a 
minimum width field. 

0 

The digit 0 is used only in the conversion of numeric 
values (integer or floats) and when you a use a minimum 
width field. It indicates that the number is to be 
preceded by 0 characters rather than spaces. 

+ 

The plus sign can only be used with signed values. It 
indicates that the value is to be preceded by a plus sign if 
it is positive. Negative values are always preceded by a 
minus sign, this cannot be disabled. 
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Space 

This attribute is similar to plus. It can only be used for 
signed values; it indicates that the value is to be preceded 
by a space if it is positive. Negative values are always 
preceded by a minus sign, this cannot be disabled. 

n 

This attribute may only be used with the numeric 
conversions g , G , f , F , o , x and x . Its effects are 
described under the appropriate conversion. 


2. The optional minimum field is a whole number constant. This field can also 
be replaced with an asterisk (*). In this case the next value from 
a r g 1 , a rg2,... is used as the value of this field, which must be an integer. 

This field specifies the minimum width for this conversion. If the converted 
value isn’t large enough to fill the minimum length then characters (space or 
0) are added to fill the space so that it is always at least minimum size. If the 
the value converted is too big then the field grows to be large enough. 

3. The optional precision field is preceded by a decimal point and must be 
followed by an integer constant. If the decimal point is not followed by a digit 
it is taken as zero, which is not the same as the absence of this precision 
field. 

This field can be an asterisk (*) in which case the next argument from 
a rg 1 ,a rg2,... is used as the value of the field. The argument must be a 
positive integer. 

For the f format, fixed point numbers, this value represents the number of 
digits after the decimal point. For the e format, exponential floating point 
format, it is the number of significant digits. By default this value is 6. This 
represents the maximum number of digits that will be generated. 

When used with the s format this is the maximum number of characters to 
write; any further characters in the string are ignored. 

4. An optional letter l which when used with the d, o , u and x formats 
indicates that the argument is of type Long. 

5. A compulsory type indicator. This is one of the characters: c, d, e, E, f, F, 
g, G, o, s, u, x, X. 


d 

writes a signed whole decimal integer of type i n t or Long. 
The result of the conversion is a sequence of digits 
preceded by a sign if the argument is negative or if the + 
attribute is used. 

u 

performs the conversion for an unsigned decimal number. 
This parameter must be of type int or Long. The result is a 
string of decimal digits. 

0 

writes a number in octal. The argument must be unsigned. 
The value is converted into a sequence of digits. If the U 
attribute is used the value converted is preceded by a zero. 
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x, X 

writes a number in base 16. The argument is supposed to be 
a string of type unsigned. The result of the conversion is a 
string of hexadecimal digits. The letters a-f are used with x 
and a-f are used with x. If the attribute tt is used then the 
characters are preceded by Ox or Ox (with x). 

c 

the argument is used as a character. A single character is 
converted. The type of the parameter can be char, short, 
i n t or Long. In the last three cases, only the least 
significant byte is used. 

s 

the argument is written as a string of characters. It must be 
a pointer to a string of characters terminated by a null 
character. If the precision format was specified then this 
indicates the maximum number of characters to write from 
the string. The string will be truncated if this value is less 
than the length of the string. 

f 

write a floating point number (of type float or double) 
without using exponential notation. A sequence of digits 
preceded by an appropriate sign and containing a decimal 
point is produced. The sign is present if the number is 
negative or the + attribute is used. The number of digits 
after the decimal point is fixed by the precision asked for (6 
by default). If the precision is 0 or the value is a whole 
number then the decimal point is omitted unless the # 
attribute is used. 

e, E 

write a floating point number (of type float or double) 
using exponential notation. The result of the conversion is 
number of the form -x.xxxxxxe-xxx (with e ) or - 
x.xxxxxxE-xxx (with e), x can be any digit. The sign 
before the number is present if the number is negative or if 
the + attribute is used. There is always exactly one digit 
before the decimal point. The number of significant digits is 
set by the precision attribute (6 by default). If the precision 
is 0 or the value has only one significant digit then the 
decimal point is omitted unless the # attribute is used. 

9/6 

write a floating point number (of type float or double) 
using fixed point or floating point notation depending on 
which would require the least characters. If the exponent is 
greater than -4 and is less than the precision asked for, the 
fixed point (f) notation is used, otherwise the exponential 
form is used. In this case if G is used then E format is used, 
if g is used then e is used. Non significant zeros and 
decimal points are suppressed unless the U attribute is 
used. 


% ’/. in the format string outputs a single 7. character. 
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printf ("To-day is the %d/ %02d/%02d \ n" , da y ,mon t h ,y ea r ) ; 

would display, for example: 

To-day is the 19/07/89 

If x = 1.34 then 

printf ("The value is %#* . *g" , 1 4, 8 ) ; 

produces 

The value is 1.34000000 

printf("%#07X\n",63); 

produces 

0000X3 F 


pri n t f ( "<%1 0 . 5s><M 0. 5 s>"," interpreter" ); 

produces 

< interxinter > 



sprintf, cprintf. 


fprintf. Help command (printf). 


PRINT WINDOW HiSoft C 


ret = p r i n t_w i n d o w ( w i n d o w_n o , string); 
int ret, window_no; 
char *string; 

Writes a string of characters at the cursor position in a window (window.no) 
that has been opened using open.window. 



Section 3.2.6, Help command (print.wi). 
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PROTOBT 

GEMDOS 

ProtobtCbuf, seriaL.no, disk.type, executable); 
int serial.no, disk.type, executable; 
char bufC512H; 

Produces a boot sector image for track 0 sector 1. buf is used for the boot 
sector image, disk. type is 2 for 80 track single-sided and 3 for 80 track 
double-sided, executable is 1 if this is to be an executable boot sector, 0 
otherwise. 

PRTBLK 

GEMDOS 

ret = PrtblkO; 
int ret; 


Produces a screen dump on the printer. 


This function returns 0 if the operation was successful. 


PTERMO 

GEMDOS 

PtermOC); 


Terminates the running program and returns to 
(normally the GEM Desktop). 

the calling program 

PTERMRES 

GEMDOS 

PtermresCbytes, return.code); 
int bytes, return.code; 


Terminates the current program, freeing only bytes of memory and return 
to the Desktop. Used for so-called TSR’ programs. Not useful in HiSoft C. 

PUNTAES 

GEMDOS 

PuntaesC); 


Reboots the AES; i.e. the whole machine. 
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PUTC 


ANSI 


//include <stdio.h> 
ret = putcCch, f p > ; 
int ret, c h ; 

FILE * f p ; 

Writes the character ch to the file f p. The returned value is the same as the 
value written, unless an error occurs. In this case, the value -1 is returned 
and the variable errno indicates the nature of the error. 



putchar, fputchar, errno. 


PUTCHAR 


UNDO 


ret= putchar(ch); 
int ret, ch; 

Writes the character ch to the standard output file stdout (the screen by 
default). The returned value is the same as the value written, unless an error 
occurs. In this case, the value -1 is returned and the variable errno indicates 
the nature of the error. 


putc, fputchar, errno. 


PUTS 


ANSI 



ret= puts(string); 

int ret; 

char * s t r i n g ; 

Writes a string of characters to the file stdout (the screen, by default). A 
new- line is written after the string. The value returned is 0 or -1 if there was 
an error, errno will give the type of error in this case. 


put! 
same as f 

puts(string) is not the same as fputsCstring, stdout). 


puts moves to the next line after writing the string. This is not the 
same as f p u t s . 



fputs, errno. 
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RAND 

ANSI 

num = randO; 
i n t num; 


Returns a random 32-bit unsigned integer. 


/^\ srand. Random. 


RANDOM 

GEMDOS 

num = RandomC); 
int num; 


Returns a random 24-bit unsigned integer. 


READ 

UNIX 


num = readCnf , buffer, bytes); 
int num, nf, bytes; 
char *buffer; 

Reads bytes from the file n f which has been opened using the UNIX call 
open. 

buffer is the address to where the bytes are read, bytes is the number of 
bytes to be read. 

num is the number of bytes successfully read. Normally this will be equal to 
bytes. However if the end of file is reached, then num will be less. 

If num is -1 then an error has occurred and errno will indicate which error. 


A 


The buffer that you are reading should be at least bytes long; otherwise 


you will destroy other variables, with possibly fatal consequences. 



open, write, errno. 


READBUT BOX HiSoft C 


ret= r e a d b u t_b o x ( b o x_n o , button_no); 
int ret, box_no, button_.no; 

Returns 1 if a button (button_no) of a dialog box (box_no) is selected. 



Section 3.3.7, Help command (readbutj. 
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READSTR_BOX HiSoft C 

string =readstr_box(box_no, field_no); 

char * s t r i n g ; 

int box_no, field_no; 

Returns the text entered by the user for an editable text field (text_no) in a 
dialog box (box_no). 



edit_box, Section 3 . 3 . 9 , Help command (readstrj. 


REALLOC 


ANSI! 


new_block = r e a l l o c ( o l d_b L o c k , new_size); 
unsigned int new_size; 

char * n e w_b Lock, *old_block; — 

This function allocates a block of memory whose length is given by 
neu.size. The contents of an old block (the memory pointed to by 
old_b Lock) are then copied to the new one and finally the old block is 
freed. 

If new__size is larger than the original block size the extra space is filled 
with zeros. If the new_si ze is smaller than the original size then only part of 
the block is copied. 



calloc, malloc, free. 


RECT I N IT 


HiSoft Cl 


rect_i ni t ( rectang le, x, y, w, h); 
short rectangleC4]; 
int x, y , w, h; 

Assign the values x , y , w and h to an array rectangle. 

x , y , w, h give the co-ordinates of the top left, the width and the height of the 
rectangle respectively. 

Thus rectangleCO] will contain x, rectangleCI] will contain y , 
rectangleC2] w, and rectangleC3D h. 
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This could also be written 


//include <gemlib.h> 

rect_init(&rectangle, x, y, w, h); 

GRECT rectangle; 
int x, y, w, h; 

GRECT is a structure containing four fields, g_x, g_y, g_w and g_h. The 
values passed as parameters are assigned to the corresponding fields in the 
structure. 



see rect_union. 


RECT INTERSECT HiSoft C 


inter = rect_intersect(rect1, r e c t 2 ) ; 
short recti C4D, rect2C43; 
int inter; 

This function determines the intersection of two rectangles (see 
rect.ini t) recti and r e c t 2 . The function returns 1 if they do overlap in 
which case rect2 will contain the intersection. If there is no intersection 0 
is returned. 


RECT POINT HiSoft C 


within = rect_poi nt ( rec t, x, y); 
short rectC43; 
int x , y ; 

Returns 1 if the co-ordinates (x, y) are within the rectangle rect (See 
r e c t _ i n i t ) . 


RECT UNION HiSoft C 


rect_uni on (recti , r e c t 2 ) ; 
short rect1C4D, rect2C43; 

Calculates the union of two rectangles. That is to say the smallest rectangle 
containing recti and rect2. rect2 is returned containing the union. 
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These two programs below do exactly the same thing: they display the 


union of two rectangles. 


# i nc lude <geml i b . h> 
GRECT arrl; 

GRECT a r r2 ; 


void ma i n ( ) 
i 

rec t_i n i t C 8 a r r 1 , 100, 100, 50, 100); 
rect_i ni t ( 8a rr2, 150, 150, 50, 100); 
re c t_un i on ( 8a r rl , 8arr2); 
printf("%d,%d," , arr2.g_x, arr2.g_y); 
pri ntf C' , %d,%d\n", arr2.g_w, arr2.g_h); 

> 

short arr1C43,arr2C4D; 
void ma i n ( ) 

{ 

r e ct_i ni t ( a r rl , 100, 100, 50, 100); 
re ct_i ni t ( a r r2, 150, 150, 50, 100); 
rect_uni on (arrl , arr2); 

printf("%d,%d,%d,%d\n", arr2C03, arr2C1D, arr2C2], arr2C3D); 


L, 


> 

Second program: 

short arrl C 4D =-C 1 00, 1 00, 5 0 , 1 00> ; 
short arr2C43 = -C150,150,50,100>; 

void ma i n ( ) 

t 

rect_union(arr1 , arr2); 

printfC" %d,%d,%d,%d\n" , arr2C0:, arr2E13, arr2C2:, arr2C3:); 

> 




ANSI 




REMOVE 


ret= remove(name); 
char *name; 
i n t ret; 

Deletes a disk file whose name is given as a parameter. 

This function returns O if the operation was successful or another value if an 
error occurred, in which case errno will indicate why. 




unlink, Ddelete, errno. 
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RENAME 


UNIX 


ret= rename (o ld_name, new_name); 
i n t ret; 

char *old_name, *new_name; 

Changes the name of the file. The file old_name is renamed to new_name. 

This function returns 0 if the operation was successful or another value if an 
error occurred, in which case errno will indicate why. 



Frename, errno. 


REPMEM 


repmemCbuf, element, size, num); 
char *buf, *element; 
int size, num; 

This function initialises the area of memory pointed to by b u f and sets up 
each element to have the same value. 


element is a pointer to a buffer containing the initial value of the elements, 
size is the size of each element in bytes, num is the number of times to 
duplicate. 



buf must be big enough, at least size*num bytes. 



memchr. 


REWIND 


ANSI 


//include <stdio.h> 
ret= rewind(fp); 
i n t ret; 

FILE * f p ; 

Move the file position of the file f p to the beginning. This is the position at 
which reading and writing occurs. The file f p must have been opened using 
f o p e n . 


The value returned is 0 if the operation was successful; non-zero otherwise. 



Calling this function is equivalent to fseek(fp,0,0). 



fseek, ftell, errno. 
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RMDIR 


UNIX 


ret= rmdi r(di r_name); 
char *d i r_name ; 
i n t ret; 

Deletes the directory (folder) named dir.name. The directory must be 
empty. 

This function returns -1 if an error occurred and 0 if the operation was 
successful. As usual errno will indicate the reason for the error. 



Dcreate, errno. 


RS ADDRALERT HiSoft C 


a Lert_adr = rs_addralert(alert_no); 
i n t aler t_n o ; 
char *a Ler t_a dr; 

This function returns the address of an alert box within the resource file 
loaded by rsrc_load. 

a Lert_no is the number of the alert box of which you wish to find the 
address. 


RS ADDRBUTTON HiSoft C 


//include <gemlib.h> 

text_adr = r s_a d d r b u t t o n ( d i a l_a d r , button_no); 
int button_no; 

OBJECT * dial _a dr; 
char *text_adr; 

This function returns the address of the string of a button or a non-editable 
text object. This is the address of the string that is displayed. 

dial_adr is the address of the dialog box (this can be found using 
r s_a dd rd i a l). The box will normally have been loaded using rsrc_load. 

b u 1 1 o n_n o is which item to find the address of. 
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RS ADDRDIAL 


HiSoft C 


//include <gemlib.h> 

dial_adr = r s_a d d r d i a L C d i a l_n o ) ; 

int dial_no; 

OBJECT * d i a L_a d r ; 

This function returns the address of a dialog box that has been loaded from a 
resource file via rsrc_load. 

d i a l_n o is the number of the dialog box that you wish to find. 


El 

fesJ see rs_drawdial. 

RS ADDREDIT HiSoft C 


//include <gemlib.h> 

text_adr = r s_a d d r e d i t ( d i a l__a d r , edit_no); 
int edi t_no; 

OBJECT * dial _a dr; 
char * t e x t_a dr; 

This function returns the address of an editable text field in a dialog box. This 
is the address where the characters typed by the user are stored. 

dia l_adr is the address of the dialog box (this can be found using 
r s_a d d rd i a l). The box will normally have been loaded using rsrc_load. 

edi t_no is which item to find the address of. 



see rs_drawdial. 


RSCONF 


GEMDOS 


RsconfCspeed, handshake, control, rsr, tsr, scr); 
int speed, handshake, control, rsr, tsr, scr; 

Configures the RS232 port. If any of the parameters is -1 then the 
corresponding attribute is not changed. 

speed contains a value between 0 and 15 which indicates the speed of 
transmission as a baud rate. 


0 

: 19200 

4 

2400 

8 : 

600 

12 : 

: 134 

1 : 

: 9600 

5 

2000 

9 : 

300 

13 : 

: 110 

2 : 

: 4800 

6 

1800 

10 

: 200 

14 : 

: 75 

3 : 

: 3600 

7 

1200 

11 

: 150 

15 : 

: 50 
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The handshake parameter indicates what sort of handshaking is to be 
used. 


0 

no handshaking (the default value) 

1 

XON/XOFF ( A S/ A Q) i.e software handshake 

2 

CTS/RTS i.e. hardware handshake 

3 

both XON/XOFF and CTS/RTS 


control indicates how bytes are transmitted: 


bit 7 

1 

bits 5,6 

number of bits (00 = 8, 01= 7, 10=6, 11=5) 

bits 3,4 

start and stop bits (00 = neither, 01= 1 start & 1 
stop, 10 = 1 Start & 1.5 stop, 11 =1 start & 2 stop). 

bit 2 

1 = parity on, 0=parity off 

bit 1 

1 = even parity, 0=even parity 

bit 0 

0 


The rsr, tsr, scr parameters set the corresponding register in the 68901. 
Thay are not normally changed. 


RS DRAWALERT HiSoft C 


button_no = r s_d ra wa l e r t ( a l e r t_no ) ; 
int button_no, alert_no; 

This function draws an alert box on the screen, waits for the user to click on 
a button and returns which button was selected. 

The index of the alert box to draw is passed as the a l e r t__n o parameter. 
This box must be part of a resource file that has been loaded with 
rsr c_ load. 



The box’s number not its address is passed as a parameter. 


RS_DRAWDIAL HiSoft C 


^include <gemlib.h> 
rs_drawdi a L (di a l_adr ); 

OBJECT * d i a l_a dr; 

This function displays a dialog box on the screen. 

The box is only drawn, this function does not wait for a mouse button click. 
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V.. 


V 


V 

C 



s_ 




The screen is saved before drawing. It can be re-displayed by using the 
r s_e rasedi a L function. 

The address of the form to display is passed as the dial_adr parameter. 
This is the value returned by rs_addrdi a l. This form must be part of a 
resource file loaded by rsrc_load. 



The address of the box, not its index is passed to this function. 


A 


This function isn’t enough to handle the complete interaction between 
the user and a form. You should also call form_do (GEM AES), and then 
restore the screen using r s_e r a s e d i a l . 


nn 

This program loads a resource file containing a dialog box (with an 
editable field edit, two buttons drivea and driveb to change the editable 
field EDIT, four radio buttons CH0ICE1, CH0ICE2, CH0ICE3 and C H o I C E 4 , 
and two exit buttons OK and cancel) and an alert string. This program is one 
of the examples on Disk 2. 

^include "example, h" 

# i nc lude <geml i b . h> 

ma i n ( ) 

< 

0BJECT*ad r_d i a l ; 
i n t o b j e c t_n o ; 
int finished; 

/* load resource file */ 

if ( ! rs rc_l oad ( " examp l e . rsc" ) ) 

{ 

/* check if error */ 
printfC" Fatal error. . .\n"); 
e x i t ( 0 ) ; 

> 

/* Address of form called DIAL */ 
adr_dial = r s_a ddrdial(DIAL); 

/* draw the dialog box */ 
r s_d rawdialCad r_d ial); 
g ra f_mouse ( M_0N, 0); 

restart: 
finished = 0; 

/ * clear the editable text field * / 

s t r cpy ( rs_a dd red i t ( ad r_d i a l , TEXT), ""); 

do 

/* give the user control */ 
object_no = f orm_do(adr_di a l, TEXT); 

/* de-select the button that caused the exit */ 
rs_obj unselect (ad r_di a l, object_no); 
r s_d rawobjectCad r_d ial, o b j e c t_n o ) ; 
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/* act depending on exit button */ 
switch (object_.no) 

case DRIVEA: 

/* put A : \ * . * in the text field * / 

strcpyCr s_a ddreditCad r_d i a l , TEXT), "A:\\*.*"); 

/* display the new text */ 

rs_drawob j ec t ( adr_di a l, TEXT); 

break ; 
case DRIVEB: 

strcpyCr s_a ddreditCad r_d i a L , TEXT), "B:\\*.*"); 
r s_d rawobjectCad r_d i a l , TEXT); 
break ; 
case OK: 

finished = 1 ; 
break ; 
case CANCEL: 

finished = 2 ; 
break ; 

> 

> 

while ( ! f i ni shed); 

/* if you click on OK, ask for confirmation */ 
if ( f i ni shed == 1 ) 
if ( rs_drawa lert (ALERT) == 2) 
goto restart; 

/* remove the form & restore the screen */ 
r s_e rasedialC); 

graf_mouse (M_OFF, 0); 

/* display the result */ 
cprintfC" Folder selected : %s\n", 

rs_add red i t ( ad r_d i a l , TEXT)); 
if ( rs_ob j s t a t e ( ad r_d i a l , CHOI CE1 ) ) 
cprintfC "Choice 1 and " ); 
else 

cprintfC "Choice 2 and " ); 

if C r s_o bjstateCad r_d i a l , CHOI CE3) ) 

cprintfC "Choice 3" ); 

else 

cprintfC "Choice 4 " ) ; 

cprintfC" have been selected\n"); 

/* Free memory used by the resource file * / 
rsr c_f ree(); 


RS.DRAWOBJECT HiSoft C 


//include <gemlib.h> 

r s_d rawob jectCdia l_a dr, objec t_no ) ; 

OBJECT * d i a l_a d r ; 
int objec t_n o ; 

This function re-draws a single object (object_no) in the dialog box given by 
the address dial_adr. 

For an example of its use see above. 
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RS ERASEDIAL HiSoft C 


r s_ erased i a l ( ) ; 

This parameterless function removes a dialog box that has been drawn with 
r s_d rawdi a l. The screen is re-drawn as it was before the dialog box was 
drawn. 


You must only use this function after calling rs_drawdiat and similarly if 
you call rs_drawdi a l you should always call r s_e r a s e d i a L . 

See the example above. 


RS OBJSELECT HiSoft C 






#include <gemlib.h> 

rs_objselect(dial_adr, object_no); 

OBJECT * dial_adr; 
i n t o b j e c t_no ; 

This function selects object number object_no in the form at address 
d i a l_a d r. 

The must be re-drawn for it to appear in inverse video. 



rs_obj unselect, rs_drawobject, rs_drawdial. 


RS_OBJSTATE HiSoft C 


c 


^include <gemlib.h> 

state = r s_o b j s t a t e ( d i a L_a d r , object_no); 

OBJECT * d i a L_a d r ; 
int object_no, state; 

This function returns the state of the object object_no in the dialog box 
given by dia L_adr. The value returned is 1 if the object is selected and 0 if 
not. 





rs_obj select, rs_drawdial. 




v- 
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RS_OBJ UNSELECT HiSoft C 


# include <gemlib.h> 

r s_o b j u n s e l e c t ( d i a l_a d r , objec t_n o ) ; 
OBJECT * d i a l_a dr; 
i n t objec t_n o ; 


This function de-selects the object object_no within the tree dial_adr. 


You should re-draw the object so that it appears as normal. 



rs_obj select, rs_drawobject, rs_drawdial. 


RS_OBJXYWH HiSoft C 


^include <gemlib.h> 

rs_ob j unse LectCdia L_adr, ob ject_no, rectangle); 

OBJECT * d i a l_a dr; 
int objec t_n o ; 
short rectangleC4]; 

This function returns the screen co-ordinates of thr object object.no 
within the dialog box d i a l_a d r. 


The co-ordinates are stored in the array rectangle whose elements will 
contain the x,y co-ordinates of the top left of the object and its width and 
height. 



rs_drawobject, rs_drawdial, rect_init, rect_point. 


RSRC FREE 


GEM AES 


ret= rsrc.f reel ); 
int ret; 

Frees the space used by resources loaded with rsrc.load. You should always 
call this function before terminating a program that calls rsrc.load. 

If an error occurs the function returns 0. 
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RSRC GADDR GEM AES 


//include <gemlib.h> 

ret= r s r c_g a dd r ( ob j e c t_t y p e , object_no, & o b j e c t_a d r ) ; 
int ret ,ob j ect_type,ob j ect_no; 

OBJECT * object_adr; 

This function returns in obj ect_adr the address of the given object 
(o b j e c t_n o) of the given type (ob j e c t_t y pe) of the loaded resource file. 

If an error occurs the function returns 0. 


RSRC LOAD GEM AES 


ret = r s r c_l oa d ( f i l e_name ) ; 
char * f i l e_n a me ; 
int ret; 

Load a resource file into memory. 

The value returned is 0 if an error occurs, for example if the file is not found 
or there is insufficient memory to load the file. 

A 

< v > The area where resource files are loaded is fixed during the 
initialisation of HiSoft C. If you are loading a substantial resource file this will 
be too small. The size of this area can be changed. See Section 1.4.13. 


RSRCOBFIX GEM AES 


//include <gemlib.h> 

rsrc_obf ix(tree_adr, object _no); 

int object _no; 

OBJECT * t re e_ad re- 
converts the co-ordinates of the object obj ect_no in the tree tree_adr 
from character co-ordinates to screen co-ordinates. 


RSRCSADDR GEM AES 


//include <gemlib.h> 

ret= rs r c_sa dd r ( ob j e c t_ty pe , object_no, object_adr); 
int r e t , o b j e c t_t y p e , ob j ect_no; 

OBJECT * o b j e c t_a dr; 

This function sets the address field of the object object__.no of type 
object_type to be object_adr. 

If an error occurs the function returns 0. 
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RWABS 


GEMDOS 


ret= Rwabs ( r e a d_w r i te, buffer, sectors, 
sector_no,drive_no) ; 

int ret, read_wri te, sectors, sector_no, drive_no; 
char *buffer; 

Read (if read_write = 0) or write (if read_write = 1) logical sectors on a 
disk. 

The number of sectors to read or write is given by sectors. The i/o starts 
at sector number secto r_n o . 

drive.no indicates which drive to read from 0=A, 1=B etc. 


SCANF 


ANSI 


object_no = scant (format, argl, a r g 2 , . . . ) ; 
char *format; 
int ob j ect.no; 

The scant function performs formatted input on the file stdi n (the 
keyboard by default). 

The first argument (format) indicates the format of the reading. Extra 
arguments are needed according to the format specified. Each of these extra 
arguments is a pointer to a variable. Each value read from the keyboard is 
stored in the variables given by these pointers. 

The value returned by s c a n f is the number of values successfully read from 
the keyboard and assigned to the variables argl,arg2,... 

The format parameter is a string indicating how to perform the read. 
There are three sorts of elements that can make up the format string: 

• White space (spaces, tab characters and newlines). 

A sequence of white space characters in the format string causes 
all white space characters input to be ignored until a non-blank 
character is entered. Exactly which white space characters are 
used in the format string is irrelevant. 

• Conversion specifications. 

Conversion specifications start with a per-cent sign %. The rest of 
the format of conversion specifications is explained later. 

• All other characters. 

Each such character must correspond to the same character in 
the input. A % in the input is represented by %% in the format 
string. 
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Reading stops when: 

• The end of file is reached (if s t d i n has been re-directed). 
Clearly reading must stop at this point. 

• There is a mis-match in the format and the characters read. Input 
stops as soon as this occurs. The remaining conversion 
specifications will be ignored. 

• The whole format string has been scanned. 

The value returned by scant is the number of successful conversions. That is 
to say the number of values assigned to the variables argl, arg2... 

If no characters can be read the function returns -1. 

The syntax for format statements is as follows: 

%*m L c 

They consist of the following elements in order. 

1 . A % character. 

2. An optional asterisk * which indicates that the conversion should be made 
as usual, but that the value obtained should not be stored in a variable. Thus 
no argument is ‘consumed’ by this conversion. 

3. A strictly positive decimal number m which gives the maximum number of 
characters to be read during the conversion. This is only used when reading 
strings of characters (%s). 

4. An optional letter L indicating that the type of a parameter is long. This is 
used with the conversion characters d, e, f t g, o, u and x. 

5. A conversion character. This must be present and should be one of c, d, e, 
f, g, h t n, o, s, u, x. 

The scant specifiers are similar to the print f ones. In some cases the 
format strings can be the same. But this doesn’t mean that a string that can 
be used for output via p r i n t f can always be used to input the string. 

The conversion characters are as follows: 


c 

Character. 

The corresponding argument must be a pointer to a 
character, i.e of type char*. The first character present 
in the input is read and stored at the address pointed to 
by the argument. Blanks are not skipped. 

d 

Decimal 

integer. 

The corresponding argument must be a pointer to a 
integer, i.e. of type int*, or Long* if the long type (l) 
indicator is present. Blanks, if any, are skipped. A + or - 
sign may be present. Characters are read until a non- 
valid digit is found. There is no check for overflow. The 
converted value is stored in the integer pointed to by 
the argument. 
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e,f ,g 

Floating 

point. 

Floating point. These three types are equivalent. The 
corresponding argument must be a pointer to a float or 
double. As both float and double are double-precision, 
the long type indicator (l) must be used. Otherwise the 
conversion will not be done correctly. 

The format required is 

CblanksDCsignDdigitsC.digitsUCexponentD 

1. Optional blank characters are ignored. 

2. An optional + or - . 

3. A sequence of digits. 

4. An optional decimal point, followed by further digits 
if present. 

5. An optional exponent consisting of a letter e or E 
followed by an optional sign and sequence of digits. 

The value calculated from the characters read is stored 
in the double precision variable pointed to by the 
corresponding argument. 

h 

short 

decimal 

integer. 

The corresponding argument must be a pointer to a 
short integer, i.e. of type short*. Blanks, if any, are 
skipped. A + or - sign may be present. Characters are 
read until a non-valid digit is found. There is no check 
for overflow. The converted value is stored in the 
integer pointed to by the argument. 

0 

Octal 

integer. 

The corresponding argument must be a pointer to a 
integer, i.e. of type int*, or Long* if the long type (L) 
indicator is present. Blanks, if any, are skipped. 
Characters are read until a non-valid octal digit is found 
(i.e not 0-7). There is no check for overflow. The 
converted value is stored in the integer pointed to by 
the argument. 

s 

Character 

string 

The corresponding argument must be a pointer to a 
character, i.e. of type char*, or array of characters. 

X 

Hexa- 

decimal 

integer. 

The corresponding argument must be a pointer to an 
integer, i.e. of type int*, or long* if the long type (1) 
indicator is present. Blanks, if any, are skipped. 
Characters are read until a non-valid hex digit is found 
(i.e not 0-9, a-f or a-f). There is no check for overflow. 
The converted value is stored in the integer pointed to 
by the argument. 


There are some characters that can be typed which will not be read by 
scant because the scant function has not been asked to read them. 
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For example, the newline character typed at the end of a line won’t be read 
by scant unless the string finishes with a space. 

This can also happen if the format string does not correspond to the user’s 
input. If scant is waiting for a number (% d) and the user types digits then 
the letters won’t be read by scant. 

All characters not read by scant remain in the input buffer and these 
characters will be handled by subsequent calls to scant. 

This problem can appear particularly if you are trying to read a character 
using %c. When using this conversion character, white space (i.e. spaces and 
new lines) are not skipped. 

If for example, you execute two scantC %c" , & c ) ; statements one after 
another and on the first call you type a character followed by Return, then 
the first character will be stored in c as you expected. But when it comes to 
the second call the character read will be the Return, which is probably not 
what you expected. 

There are two ways to get round this problem. 

The first is to always call g e t c h a r ( ) after scant to read the newline 
character. 

The second method is to force the input buffer to be emptied before calling 
scant. To do this use tseek(stdin,0,2). Don’t forget to include the 
<stdio.h> file. 



fscanf, sscanf, sprintf. 


SCRP_RE AD 

GEM AES 

ret= scrp_read(address); 

i n t ret; 

char * a d d r e s s ; 


Reads the name of the clipboard directory. 


SCRP_WRITE 

GEM AES 

ret= scrp_wri te(address); 

i n t ret; 

char * a d d r e s s ; 


Changes the name of the clipboard directory. 
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SELECT_MENU HiSoft C 


state = s e L e c t_m e n u ( t i t L e ) ; 
int state, title; 

Select or de-select a menu title. 


The menu must have been created using the i ni t_menu function. 

title is the number of the menu title as returned by title__menu. The 
value returned is the new state of the menu. 1 meaning selected, 0 otherwise. 



init_menu, itemjmenu. Section 3.4.6, Help command (select_m). 


SETBUF 


ANSI 


//include <stdio.h> 
setbufCfp, buffer); 

FILE * f p ; 

char bufferCBUFSIZH; 

This function must be used after a file has been opened with fopen, but 
before any other operation on the file (read or write). 

The buffer whose address is passed as a parameter is used to replace the 
default buffer for input-output on this file. 

This buffer must be of size B u F s I z . 

If the address passed is zero then the i/o on this file is performed without 
using a buffer, causing a physical i/o operation for each system call. 

The first parameter is the file pointer for the file concerned. 


SETCOLOR GEMDOS 


Setcolor(colour_no, pallete_value); 
int colour_no, pa l lete_va lue; 

Sets the palette (to pallet e_va lue) for the colour co lour_no. 


SETEXC 


GEMDOS 


s e t e x c ( v e c t o r_n o , v e c t o r_v a l u e ) ; 

int vector_no; 

char *vector_value; 

Sets the interrupt or exception vector (given by vector_no between 0 and 
255) to the vector_value passed as a parameter. 


Page 246 


HiSoft C 


Library Reference 






L 


SETNBUF 


ANSI 


tt include <stdio.h> 
setnbuf(fp); 

FILE * f p; 

This function lets you suppress the buffering of a given file. 

After calling this function every i/o call for the file given by the file pointer f p 
will cause a physical i/o operation. 


SETPALLETE GEMDOS 


Setpa L LetteCpa Lette_adr); 
short patetteC 16 D; 

Sets the pallette of all 16 colours. 


SETPRT 


GEMDOS 


n_config = Setprt(config); 
int config; 

Read or write the printer configuration. 

If the parameter is -1, then the configuration is read by the function. 
Otherwise this parameter is a bitmap giving the new configuration as follows: 


bit 

value 0 

value 1 

0 

dot matrix 

daisy wheel 

1 

colour 

black and white 

2 

Atari printer 

Epson 

5 

draft mode 

final mode 


parallel printer 

serial 

5 

continuous stationery 

single sheet 

15 

must be 6 

1 


The function returns the new printer configuration. 
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SETSCREEN 


GEMDOS 


S e t s c r e e n ( L o g i c a l_a d r , p h y s i c a l_a d r , resolution); 
char *logi ca l_adr, *physi ca L_adr; 
int resolution; 

Modifies the screen addresses and/or the screen resolution. 

The parameters are the logical screen address, the physical screen address 
and the desired resolution (0, 1 or 2). 

If a parameter is negative the corresponding parameter is not changed. 


SETTIME 


GEMDOS 


ret= settime(date_time); 
long ret, date_time; 

Sets the intelligent keyboard controller’s idea of the date and time. The same 
format as Tgetdate and Tgettime is used. 

The value returned is the time that has been set. 


SHEL ENVRN GEM AES 


shel_envrn(address,name); 
char *address, *name; 

Finds the address of an environment variable. 


SHEL FIND 


GEM AES 


ret= shel_find(buffer); 

int ret; 

char *buf f er; 

Searches for a file name using the AES path. 


SHEL READ 


GEM AES 


shel_read(appli cation_name, command_line); 
char * a p p l i c a t i o n_n a me , * c omma n d_ l i n e ; 

Reads the name of the running application and its command line. 
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SIN 


ANSI 


ret= sin(val); 
double ret/val; 

Calculates the sine of an angle in radians. Both the argument and the result 
are double reals. 



SINH 


ANSI 


ret= sinhCval); 
double ret,val; 


Calculates the hyperbolic sine of the angle given as a parameter. Both the 
argument and the result are double reals. 

If the argument is too large for the s i n h to be calculated then errno will 
indicate this error. 



cosh, tanh, errno. 


SPRINTF 


ANSI 


length = sprintfCstring, format, argl, a r g 2 , . . . ) ; 
int length; 

char ♦string, Mormat; 

This function is similar to pr intf except that instead of writing to the 
screen it writes to a string that is passed as a parameter. 



This function lets you easily convert from numeric types to ASCII. 


tJCT 

The following function converts an integer (number) into a string 
(string) containing its hexadecimal representation. 

void conv_hex(number,string) 
int number; 
char * s t r i n g ; 

< 

spri ntfCstring," % # x " , number) ; 

> 



cprintf. fprintf, printf. 
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SORT 


ANSI 


ret= sqrt(val); 
double ret, val; 

Returns the square root of the number passed as a parameter. Both the 
parameter and the result are double precision real numbers. 


SRAND 


ANSI 


srand(value); 
unsigned int value; 

Re-seed the random number generator. 



rand. 


SQSORT 


UNIX 


sqsort(tab,n); 
short * t a b ; 
int n ; 

This function sorts an array of short integers. 

The array of shorts is modified so that they are in increasing order. 



lqsort, dqsort, tqsort. 


SSCANF 


ANSI 


number = sscanf (stri ng, format, argl, a r g 2 , . - . ) ; 
int number; 

char *stri ng, *format; 


This function is similar to scant except that the characters, instead of being 
read from the keyboard, are read from a string (string) that is passed as a 
parameter to the sscanf function. 


a 


This function may be used to perform ASCII to numeric conversion for 
all the types used by scant. 
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The following function converts a string (string) containing a 
hexadecimal digit into an integer. The converted value is returned by the 
function. If an error occurs -1 is returned. 

int c on v_h e x ( s t r i n g ) 
char * s t r i n g ; 

int number; 

if ( isscanf (string," %x" ,&number)) 
number = -1; 

return(number); 

> 



cscanf, fscanf, scanf. 


STD 


ANSI 


#include <stdio.h> 
FILE * s t d i n ; 

/* 

FILE 

♦stdout; 

/* 

FILE 

♦stderr; 

/* 

FILE 

♦stdaux; 

/* 

FILE 

♦stdprn; 

/* 


default standard input file*/ 
default standard output file */ 
default error file */ 
serial i/o file */ 
pr i nter file */ 


These identifiers are defined in the file stdio.h. 


They represent the files that are always opened when you run your program. 

s t d i n is the input file that is used by scanf, getchar, etc. If you wish to 
take input from a file rather than from the screen, all you need to do is re- 
direct to this file. 


s t d o u t is the output file used by printf, putchar, etc. If you want the 
output to go to a file all you need to do is re-direct s t d o u t . 

stderr is the file that is used to write error messages. 

stdaux corresponds to a file open for read /write to the serial port. 

stdprn is an opened output file for the printer. 
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li&J The following program re-directs the standard output (stdout) to the 
file text.txt on disk. 


#i nc Lude <stdi o . h> 

FILE *sv_stdout; 

FILE *fp; 
void ma i n ( ) 

/* make a copy of stdout */ 

sv_stdout = fdopen(dup(fileno(stdout)), "w" ); 

/ * open the file to replace stdout * / 
if (fp = f openC" text . txt", "w")) 
i 

/* assign the new file to stdout */ 
dup2(fi LenoCfp), fi leno(stdout)); 
printfC'This is written to the text file"); 
/* restore the normal stdout */ 
dup2(fileno(s v_s tdout), fileno(stdout)); 
printfC'This is written to the screen\n"); 
fclose(fp); 

> 

else 

printf ("Error number %d\n", errno); 
fclose(s v_s t d o u t ) ; 

> 



Writes the contents of some variables to the printer. 


^include <stdio.h> 
void mainC) 

{. 

i n t i ; 

char timeCIOD; 
i = t i me r_v a l u e ( ) ; 
strtime(time); 

fprintf(stdprn, "It is %s\n",time); 
fprintf(stdprn, "Timer value : %d\n", i); 

fflush(stdprn); 

} 


STOP 


HiSoft C 


s t o p ( ) ; 

Stops the execution of the file and returns to the HiSoft C editor. 
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STRCAT 


ANSI 


ptr = strcatCstringl, s t r i n g 2 ) ; 
char * p t r , *string1, *string2; 

This function copies the string s t r i n g 2 to the end of stringl. stringl 
thus becomes longer including all the characters of s t r i n g 2 . 

The value returned is a pointer to stringl. 


A stringl must correspond to an area large enough to contain all the 
characters of the two strings. 



This program writes the string 


qwertyu 


opasdfgh. 


char stringl C203 = "qwertyui op"; 

char string2C8D = " asdfgh"; 

void main() 
i 

puts(strcat(string1,string2)); 

> 



stmcat. 


STRCHR 


ANSI 


p = strchrCstring, ch); 
char * p , * s t r i n g ; 

char c h ; 

Searches the string passed as a parameter for the first occurrence of the 
character ch. 

The pointer is returned pointing to the place in the string where the 
character was found. 

If the character isn’t present in the string, 0 is returned. 



strrchr, memccpy. 
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STRCMP 


ANSI 


comparison = strcmp(string1, string2); 
char *string1, *string2; 
int comparison; 

This function compares stringl and s t r i n g 2 . The two strings are 
compared character by character. The comparison continues until all the 
characters have been compared if the strings are equal or until the first time 
two different strings are found. 

stringl is less than s t r i n g 2 if the first character that is found to be 
different is less in stringl than in s t r i n g 2 . 

The value returned is zero if the strings are equal, positive if stringl is 
greater than s t r i n g 2 or negative if stringl is less than s t r i n g 2 . 



strncmp, stricmp. 


STRCPY 


ANSI 


ptr = strcpyCstringl, s t r i n g 2 ) ; 
char *ptr, * s t r i n g 1 , *string2; 

This function copies string2 to stringl. The characters that were 
originally in stringl are deleted. 

The value returned is a pointer to stringl. 



stringl 


s t r i n g 2. 


must point to an area of memory large enough to contain 


STRCSPN 


ANSI 


Ing = strcspn(string, chs); 
int l n g ; 

char *chs / * s t r i n g ; 

This function searches for the first character in string that is not one of the 
characters in chs. 

The value returned is the number of characters ignored until a character in 
chs was found. 



strspn. 
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STRDATE 


date = strdate(buffer); 
char bufferC93; 
char * d a t e ; 

This function returns the current date in the form of a string: "dd/mm/yy". 

The date is written to the buffer that is passed as a parameter. The value 
returned is equal to the parameter. 



char bufferC9D; 
void main() 

printfC" Today is %s\n",strdate(buffer)); 

> 



strtime. 


STRGETFN 


HiSoft C 


strgetf n(f i te_name, drive, path, name, extension); 
char *f i L e_name ; 

char *drive, *path, * n a m e , *extension; 

This function creates a full file name from a drive, a path, a filename and an 
extension. 


The first parameter is an array of characters where the name will be stored. 

The four other parameters are strings containing the drive, directory, name 
and extension respectively. 



The f i L e_name array must be big enough! 



char f i L e_name C60] = "d:\\hc\\examples\\strgetfn.c" ; 
char driveC4D, pathC40D, nameCIOD, extC4D; 
void mainO 

strsplf n(f i le_name, drive, path, name, ext); 

/* drive is now "d:", path " \ h c\ e x amp l e s " */ 

/* name is now "strgetfn", ext "c" */ 
s t rge t f n ( f i L e_name, "a:", "\\", "he", "prg"); 

/* file_name is now "a:\hc.prg" */ 

> 



strsplfn. 
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STRICMP 

ANSI 


comparison = stricmp(string1,string2); 

int comparison; 

char *string1,*string2; 

This function compares two strings. It is similar to st rcmp except that it 
ignores differences between upper and lower case letters. 

The value returned is negative, zero, or positive depending on whether 
s t r i n g 1 is less, equal or greater than s t r i n g 2 respectively as for strcmp. 

a strcmp, stmicmp, stmcmp. 


STRLEN 

ANSI 

Length = strlen(string); 
int Length; 



char * s t r i n g ; 

This function returns the length of the string passed as a parameter. 
SB strlenC'abc") returns 3 . 


STRLWR 

UNIX 

ch = strLwr(string); 
char * c h , string; 



This function converts all upper case letters in the string passed as a 
parameter to lower case. 

The value returned is a pointer to a string equal to the value passed as a 
parameter. 

ES] puts(strLwr("Abcl2DE&" ) ); writes a b c 1 2 d e & on the screen 
A strupr. 
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STRNCAT 


ANSI 


ptr = strncatCstringl, s t r i n g 2 , lng); 
char * p t r , *string1, * s t r i n g 2 ; 
i n t L n g ; 

This function copies s t r i n g 2 to the end of s t r i n g 1 . Thus s t r i n g 1 is made 
longer using characters from s t r i n g 2 . 

A maximum l n g characters will be added to s t r i n g 1 . 


The value returned is a pointer to s t r i n g 1 . 


A 


s t r i n g 1 must point to an area of memory that is large enough to 


contain all the characters of the new string. 



This program wTites the string "qwerty 


on the screen 


char stringl C10D = "qwer"; 
char string2C6D = "tyuio" ; 
void main() 

< 

puts(strncat(string1, string2, 2 ) ) ; 

> 



strcat. 


STRNCMP 


ANSI 


comparison = strcmpCstringl, s t r i n g 2 , lng); 
char *string1, * s t r i n g 2 ; 
int comparison, l n g ; 

This function compares stringl and stri ng2. The two strings are 
compared until either 

(a) lng characters have been compared and the strings are equal thus far. 0 
is returned in this case. 


(b) all the characters have been compared and the strings are equal. Again 0 
is returned. 

(c) Two different characters are found. If the character from stringl is less 
than that from string 2 then a negative integer is returned, otherwise a 
positive integer is returned. 


Thus strncmp is like strcmp but a maximum of lng characters are 
compared. 



strcmp, stricmp. 
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STRNCPY 


ANSI 


ptr = strncpy(stri ngl, string2, Lng); 
char * p t r , * s t r i n g 1 , * s t r i n g 2 ; 

i n t l n g ; 

This function copies up to Lng characters from s t r i n g 2 to stringl. The 
characters that were originally in stringl are deleted. 

The value returned is a pointer to stringl. 

If s t r i ng 2 is shorter than Lng, null (0) characters are added until a total of 
Lng characters has been added. 

If string2 is longer than Lng only the first Lng characters are copied and 
the string is not terminated by zero. 


A 


stringl must point to an area of memory that is large enough to 


receive the new string. 



strcpy, memcpy. 


STRNICMP 


ANSI 


comparison = strni cmp(string1 , s t r i n g 2 , Lng); 
int comparison, Lng; 
char *stri ngl ,*string2; 

This function compares up to the first L n g characters of the two strings 
stringl and s t r i n g 2 . This is similar to strncmp except that the 
corresponding upper and lower case letters are treated as the same. 

The value returned is negative, zero or positive, depending on whether 
stringl is less than, equal, or greater than string2 as for strncmp. 



strcmp, stricmp, strncmp. 


STRREV 


UNIX 


ch = strrev(string); 
char *ch, * s t r i n g ; 

This function reverses the order of the characters in the string that is passed 
as a parameter. 

The returned value is a pointer to the same string. 
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STRSPLFN 


s t p s p L f n ( f i L e_na me , drive, path, name, extension); 
char * f i l e_name; 

char * d r i v e , * p a t h , * n a m e , *extension; 

This function splits a full file name into its individual components. 

These components are the drive, the path (directory), the name and the 
extension. 

The first parameter is a string of characters containing the file name to 
analyse. 

The four other parameters are arrays of characters where the drive, path, 
name and extension will be stored. 


c 



The arrays must be big enough! 



strgetfn. 


STRSPN 


ANSI 


Ing = strspn(string, chs); 
i n t l n g ; 

char * s t r i ng , * c h s ; 

This finds the number of characters at the start of string that are contained 
in c h s . 

Thus the returned value is the number of characters ignored whilst finding 
the first character that is not in the string chs. 




strcspn. 
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HiSoft C 


time = strtime(buffer); 
char bufferC9D; 
char *time; 

This function returns the current time in a string of characters of the form 
"hh:mm:ss". 

The time is stored in the buffer passed as a parameter. The returned value is 
also equal to buffer. 



char bufferC93; 
void main() 
t 

printfC" It is %s\n" / strtime(buf f er ) ); 

> 



strdate, timer_value. 


STRTOK 


ANSI 


ch = strtok(string, chs); 
char * c h , ^string, *chs; 

Splits a string into a string of tokens. 

This function considers the parameter string to be made up of tokens 
separated by one or more characters from the string chs. 

A sequence of calls to this function returns these tokens one at a time. 

The first time the function is called a pointer to the first token found in 
string is returned. To find subsequent tokens, 0 is passed instead of 
string. The function will then return a pointer to the second token, then 
the third etc. 

When the strtok function returns 0 this means that no further tokens are 
present in the string. 


The following program writes the words contained in the string 
bbb ccc d dd " on separate lines. 


a a a 


char *string = " a a a bbb ccc ddd" ; 

char * c h ; 
void mainC) 
i 

ch = strtokCstring," "); 
d o 

puts(ch); 

whileCch = strtokCO, " " ) ) ; 

> 
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o o 


STRTOL 


UNIX 





n = strtoKstring, &end_pos, base); 

int n, base; 

char ^string, *end_pos; 

This function converts a string of characters into a long integer and returns 
this as the value of the function. 

The string must contain only valid digits from 0-9, a-z and A-Z to form a 
number in the given base from 2 to 36. 

The function ignores blanks at the start of the string and will note an initial + 
or - sign. It stops, however, when an illegal character is found. 

When it returns end_pos points to the first illegal character (or the null at 
the end) of the string. 


E J strtoK" 1000" ,&p,l6) returns the value 4096 = 1000 Hex. 





sscanf. 


STRUPR 


UNIX 




ch = strupr(string); 
char * c h , string; 

This function converts all the lower case letters in the string passed as a 
parameter into upper case. 

The value returned is a pointer to the string. 


a putsCstrlwrC" Abc12DE8" ) ) writes ABC12DE& on the screen. 



strlwr. 


SUPER 


GEMDOS 






old_pointer = Super(stack_ptr ) ; 
char *old_poi nter, *stack_ptr; 

Change to 68000 supervisor or user mode. 

If you are about to enter supervisor mode, stack_ptr is the value to use as 
the supervisor stack pointer. The pointer returned is the current user stack 
pointer. 

When returning to user mode, s t a c k_p t r is the value to be used for the user 
mode stack. 
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SUPEXEC 

GEMDOS 

ret= S u p e x e c ( r o u t i n e_a d r ) ; 
long ret; 

char *routi ne_adr; 


Executes an assembly language routine in supervisor mode. The value 
returned by the function is the value returned by the routine. 

SVERSION 

GEMDOS 

version_no = SversionC); 
i n t versio n_n o ; 


Returns the GEMDOS version number. 


TAN 

ANSI 


ret= tan(val); 
double ret,val; 

Calculates the tangent of the angle (in radians) that is passed as a parameter. 
The argument and the return value are both double reals. 



TANH 


ANSI 


ret= tanh(val); 
double ret/Val; 

Calculates the hyperbolic tangent of the argument passed as a parameter. 
The argument and the return value are both double reals. 



sinh, cosh, errno. 
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TELL 


UNIX 


pos = tell(nf); 
i n t pos; 
i n t n f ; 

Returns the current file position in the UNIX file nf (opened with open) 
where the next byte will be read or written. 



This position may be changed using L s e e k . 


TEXT BOX 


HiSoft Cl 


no_object = text_box(box_no, x, y, text); 
int no_object, box_no, x, y; 
char * t e x t ; 

Adds an object of type text into a dialog box created by i n i t_box. 
See Section 3.3.4 for a description of this function. 


c 


TGETDATE GEMDOS 


date = TgetdateC ); 
int date; 

Returns the current date in the following format: 


bits 0 to 4 

Day (6-31) 

bits 5 to 8 

Month (1-12) 

bits 9 to 15 

Year (0-127) 0=1980, 1 = 1981... 




TGETTIME 


GEMDOSI 




time = TgettimeO; 
int time; 

Returns the current time in the following format: 


bits 0 to 4 

Seconds (0-29) 0=0 sec, 1=2 sec etc 

bits 5 to 10 

Minutes (6-59) 

bits 11 to 15 

Hours (0-11) 1 




c 
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TICKCAL 

GEMDOS 

base = TickcalC); 
int base; 


Returns the clock tick interval in milliseconds. 


TIMER.VALUE 

HiSoft C 

value = t i me r_va l u e ( ) ; 
int value; 


This function returns the video clock frequency in Hertz. 60 (colour monitor) 
or 70 (monochrome monitor). 

TITLE.MENU 

HiSoft C 

no_ti tie = t i t l e_me n u ( t i t l e_n a m e ) ; 
int n o_ title; 
char *title__name; 


Adds a title bar to a menu. The menu must have 
i n i t__m e n u . 

been created with 

See Section 3.4.3 for the description of this function. 


TOASCII 

ANSI 


new_ch = toascii(ch); 
int new_ch, ch; 

This function converts a character (between 0 and 255] to ASCII (code<128] 
by removing the top bit. 

The function returns the new character code. 


TOLOWER ANSI 


nch = tolower(ch); 
int nch, ch; 

This function converts an upper case letter (passed as an integer) to lower 
case. If the character isn’t an upper case letter then the value is returned 
unchanged. 



toupper, islower. 
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TOUPPER 




ANSI 





nch = toupper(ch); 
int nch,ch; 

This function converts a lower case letter (passed as an integer) to upper 
case. If the character isn’t a lower case letter then the value is returned 
unchanged. 



tolower, isupper. 



TQSORT 


ANSI 








tqsort(arr,n); 
char * a r r C x x ] ; 
int n ; 

This function formats an array (arr) of n pointers to string into increasing 
order. 


The array of pointers is modified in situ. 


A 


It is not the values of the pointers, but the values of the strings that are 


used for the sort. 


IiEJ The following program sorts an array of three strings into alphabetical 
order, and writes them in that order. 


The array arr is initialised to contain three pointers. The first points to the 
string "zzzz", the second to " a a " and the third to "zer". After the sort, 
the order of the pointers is modified. The first points to "aa", the second to 
"zer" and the third to "zzzz". The strings themselves do not move. 


char *tabC3] = { , 'zzzz" / "aa" / "zer"); 

void mai n( ) 

tsqort(arr,3); 
p u t s ( a r r C 0 ] ) ; 
puts(arrCID); 
puts(arrE2]); 

> 



lqsort, sqsort, dqsort. 
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TRACE OFF HiSoft C 


trac e_o f f ( ) ; 

This function switches off single step mode. At the same, the display of 
variables is suppressed. 



trace_on, var_on, var_off. Section 1.4.3. 


TRACE ON HiSoft C 


trace_on(); 

This function switches on single step mode. 



trace_off, var_on, var_off. Section 


1.4.3. 


GEMDOS 


TSETDATE 


ret= Tsetdate (date) ; 
int date, ret; 

Sets the date using the following format 



bits 0 to 4 

Day (0-31) 


bits 5 to 8 

Month (1-12) 

bits 9 to 15 

Year (6-127) 6=1980, 1 = 1981... 

The value returned is 0 if the date is valid. 


TSETTIME 

GEMDOS 

ret = 

Tsettime(time) 

r 


int time, ret; 



Sets the time, using the following format: 



bits 0 to 4 

Seconds (0-29) 0=0 sec, 1=2 sec etc 



bits 5 to 10 

Minutes (0-59) 



bits 11 to 15 

Hours (6-11) 
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UNGETC 


ANSI 


#i nc lude <stdi o . h> 
ret= ungetcCch, f p ) ; 
int ret, ch; 

FILE * f p ; 

This function cancels the affect of the last call to the f getc function. The 
next character to be read from the file f p will be ch. 


A This function may not be called twice for a file between two reads of 
that file. Only one character can be ‘put back’. 


UNLINK 


UNIX 






ret= unlink(name); 
char * n a m e ; 
int ret; 

Deletes the disk file called name that is passed as a parameter. 

This function returns 0 if the operation was successful, or a non-zero if an 
error occurred in which case errno will indicate the source of the error. 



remove, Ddelete, ermo. 


V ARC 


GEM VDI 



v_arc(vdi_handle, x, y, radius, anglel, angle2); 
int vdi_handle, x, y, radius, anglel, angle 2; 

Draws a circular arc of centre (x,y) of the given radius between the angles 
anglel and a n g l e 2 . The angles should be between 0 and 3600 (tenths of 
degrees). 


HiSoft Cl 


VAR OFF 





v a r_o f f ( ) ; 

Stops the display of variables during execution. 



trace_on. Section 1.4.4. 




Library Reference 


HiSoft C 


Page 267 


VAR ON HiSoft C 


v a r_o n ( ) ; 

Starts the display of variables on the screen during execution. Trace mode 
must already be active. 

trace_on. Section 1.4.4. 

V BAR 


GEM VDI 



v_b a r(vdi_hand le, arr_xy); 
int vdi_handle; 
short arr_xyC4D; 

Draw a rectangle with the current attributes. 

arr.xy contains the (x,y) co-ordinates of two opposite corners of the 
rectangle. 


V.CIRCLE 

GEM VDI 

v_c i r c l e C vd i _ha n d l e , x, y, radius); 
int vdi_handle, x, y, radius; 


Draws a circle centred at (x,y) with the given r a d i us. 


V_CLRWK 

GEM VDI 

v_clrwk(vdi_handle); 
int vdi__handle; 


Clears the screen. 


V_CLSVWK 

GEM VDI 

v_clsvwk(vdi_handle) ; 


Close the virtual workstation opened using v_opnvwk. 


V_CONTOURFILL 

GEM VDI 


v_contourf i Ll(vdi_handle, x, y, f i L l_c o L o u r ) ; 
int vdi_handte, x, y, fill_colour; 

Performs a seed fill in the f i l Lcolour starting at the co-ordinates (x,y). 
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V_CU RDOWN 

GEM VDI 

v_curdown(vdi_handle); 
int vdi_handle; 


Moves the text cursor one line down. 


v_enter_cur. 


V.CURHOME 

GEM VDI 

v_curhome (vdi_handle) ; 
int vdi_handle; 


Moves the text cursor to the top left of the screen. 


v_enter_cur. 


V_CURLEFT 

GEM VDI 

v_curleft(vdi_handle); 
int vdi_handle; 


Move the cursor left one character. 


v_enter_cur. 


V_CU RRIGHT 

GEM VDI 

v_curright(vdi_handle); 
int vdi_handle; 


Move the text cursor right one character. 


v_enter_cur. 



Library Reference HiSoft C Page 269 


V CURTEXT GEM VDI 


v_cur(vdi_hand Le, string); 
int vd i_h a n d l e ; 
char ^string 


Display a string of text at the current cursor position. 



v_enter_cur. 


V CURUP 


GEM VDI 


v__c ur(vdi_handle); 
int vdi_handle; 

Move the text cursor up one line. 



v_enter_cur. 


V DSPCUR 


GEM VDI 


v_dspcu r ( vd i_ha nd L e , x, y); 
int vdi_handle, x, y; 

Display the mouse cursor at position (x,y). 


V EEOL 


GEM VDI 


v_eeol (vdi_handle); 
int vdi_handle; 

Clear the screen from the current cursor position to the end of the current 
line. 



v_enter_cur. 


V EEOS 


GEM VDI 


v_e eos(vdi_handle); 
int vdi_handle; 

Clears the text screen starting at the current cursor position. 



v_enter_cur. 


Page 270 


HiSoft C 


Library Reference 


v_ 



V_ELLARC GEM VDI 

V— 

v_eL La rc (vdi_hand Le, x, y, x_radius, y_radius, 
start_angLe, finis h_a n g L e ) ; 
int vdi_handLe, x, y, x_radius, y_radius, 
start_angLe, f i ni sh_ang Le; 


Draws an elliptical arc based on centre (x,y) and radii x_radius and 
y_radius between start_angLe and f i n i s h_a n g L e . The two angles are 
measured in tenths of degrees (that is between 0 and 3600). 


V_ELLIPSE GEM VDI 

v./ 

v_e L L i ps e ( vd i_h a nd L e , x, y, x_radius, y_radius); 
int vd i_ha nd L e , x, y, x_radius, y_radius; 

V. 

Draws an ellipse with centre (x,y), x radius, x.radius and y radius, 
y_radius. 


V_ELLPIE GEM VDI 




v_e L Lpi e ( vdi_hand Le, x, y, x_radius, y_radius, 
start_angLe, f i n i s h_a ng L e ) ; 
int vd i_ha nd L e , x, y, x_radius, y_radius, 

start_angLe, f i ni sh_ang L e; 

Draws an elliptical pie slice given the centre (x,y), radius, start_angle 
and f i ni sh_ang Le. The angles are measured in tenths of degrees between 0 
and 3600. 

V ENTER CUR GEM VDI 





v_enter_cur(vdi_handle); 
int vdi_handle; 

Enter text mode. The screen is cleared and a flashing cursor appears. 


VEX BUTV 


GEM VDI 




vex_butv(vdi_handle, new_adr, old_adr); 

int vdi_handle; 

char *new_adr, *oLd_adr; 

Modifies the mouse interrupt vector. 
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VEX.CURV 

GEM VDI 

v e x_c u r v ( v d i __h a n d l e , new_adr , 
int vd i_h a nd L e ; 

o t d_a d r ) ; 


char *new_adr, *old_adr; 

Modifies the end of mouse cursor drawing vector. 


V EXIT.CUR 

GEM VDI 

v__exi t_cur(vdi_handle); 



int vdi_handle; 

Leaves text mode. The screen is cleared and the flashing cursor disappears. 


VEX_MOTV 

GEM VDI 

vex_motv(vdi_handle / new_adr, 

int vdi_handle; 

char *new_adr, *old_adr; 

Modifies the mouse movement vector. 

o L d_a d r ) ; 

VEX_TIMV 

GEM VDI 

v e x_t i m v ( v d i _h a n d l e , new_adr, 

int vdi__handle; 

char *new_adr, * o L d_a d r ; 

Modifies the timer interrupt vector. 

o l d_a d r ) ; 

V_FILLAREA 

GEM VDI 


v_f i l l a r e a ( v d i_h a n d L e , n, arr_xy); 
int vdi_handle, n; 
short a r r_x y C n * 2 H ; 

Draws a filled polygon containing n points. The array arr_xy contains the 
co-ordinates of all the points in the polygon (xO,yO, xl,yl,...). 


V_GET_PIXEL 

GEM VDI 


v_ge t_pi xe l ( vdi__hand le, x, y, &rgb_colour, &colour_no); 

int vdi_handle, x, y; 

short rgb_colour, colour_no; 

Returns the colour of the point (x,y). 
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V.GTEXT 

GEM VDI 

v_g text (vdi_handLe, x, y, string) ; 
int vdi_handLe, x, y; 
char * s t r i n g ; 


Displays a string of graphics text characters, 
character is given by (x,y). 

The position of the first 

V_HIDE_C 

GEM VDI 

v_hide_c(vdi_handLe); 
int vdi_handLe; 


Hides the mouse cursor. 


V_JUSTIFIED 

GEM VDI 


V_j US t i f i ed ( vd i_h a nd L e , x, y, string. 

Length, w o r d_s p a c i n g , c h a r_s p a c i n g ) ; 
int vdi_handle, x, y. Length, wo rd_s pa c i ng , c h a r_s p a c i n g ; 
char ^string; 

Display a justified graphics text string starting at co-ordinates (x,y) in a 
width of Length pixels. 

If wo rd_spa c i ng = 1 then spaces may be added between words and/or if 

c ha r_s pacing = 1 then space may be added between characters. 


V OPNVWK GEM VDI 


v__o pnvwkCarrl, &vdi_handLe, arr2); 
short vdi_handLe, arrICIID, arr2C57D; 

Initialise a virtual workstation for GEMVDI. 

It is not necessary to call this function when using HiSoft C because HiSoft C 
has already done this. 


To find the vdi_handLe use g r a f_h a n d L e . 


V PIESLICE 


GEM VDI 


v_pi esLi ce ( vd i_ha nd L e , x, y, radius, start_angLe, f i n i s h_a ng L e ) ; 
int vd i_hand L e , x, y, radius, start_angLe, f i n i s h_a ng L e ; 

Draws a circular pie slice centred on (x,y) of the specified radi us, between 
the star t _a n g L e and the f i n i s h_a n g L e . The angles are expressed in 
tenths of a degree. 
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V_PLINE 

GEM VDI 

v_pLine(vdi_handle, n, arr_xy); 
int vdi_handle, n; 
short arr_xy[n*2]; 



Draws a set of straight lines joining the n points stored in the array a r r_xy 
(xO, yO, xl, yl. x2. y 2...). 


V__M ARKER 

GEM VDI 

v_pma r ke r ( vd i_h a nd L e , n, arr_xy); 
int vdi_handle, n; 
short arr_xyCn*2]; 



Draw n markers whose co-ordinates are stored in the array arr_xy 


(xO.yO.xl.yl...). 


VQ.CHCELLS 

GEM VDI 


vq_chcells(vdi_handle, &screen_height, &screen_wi dth ) ; 


int vd i_h a nd l e ; 

short s c r e e n_h e i g h t , screen_wi dth; 
Returns the size of the screen in characters. 


VQ.COLOR 

GEM VDI 

vq_coLor(vdi_handle, colour_no, va Lue_type, 
int vdi_handle, colour_no, value_type; 
short r g b_a r r l 3 ] ; 

Returns the representation of a colour in rgb units. 

r g b_a rr); 

VQ.CURADDRESS 

GEM VDI 

v q_c u r a d d r e s s ( v d i _h a n d l e , Srow, Scolumn); 
int vdi_handle; 
short row, column; 

Return the current text cursor position. 
v_enter_cur. 
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VQ_EXTND 

GEM VDI 

vq_e x t nd ( vd i _h a nd L e , which, tab); 
int vdi_handle, which; 
short tabC573; 


Returns information on the given virtual workstation. 


VQJNMODE 

GEM VDI 

vq_i nmod e ( vd i_h a nd L e , dev_type, & i n p u t_mo d e ) ; 
int vdi_handle, dev_type; 
short input_mode; 


Returns the current input mode of a given device. 


VQF_ATTRIBUTES 

GEM VDI 

v q f _a ttributes(vdi_handle,fi l L_t ype); 
int vdi_handle; 
short fitl_typeC4D; 


Returns the current fill area attributes (type, colour, style and writing mode 
in that order). 

VQ_KEY_S 

GEM VDI 

v q_k e y_s (vdi_handle, &ke y_s t a t e ) ; 
int vdi_handle; 
short k e y_s t a t e ; 


Returns the state of the control keys: right Shift (bit 0), 
Control (bit 2), and Alternate (bit 3). 

left Shift (bit 1). 

The corresponding bit is 1 if the key is down. 


VQL_ATTRIBUTES 

GEM VDI 




v q l_a ttributes(vdi_handle,Lin e_t y p e ) ; 
int vd i_h a nd l e ; 
short l i ne_typeC4!]; 

Returns in the array line_type information on the current line attributes 
(type, colour, writing mode and line width in that order). 


v 
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VQM.ATTRIBUTES 

GEM VDI 

vqm_attri butes(vdi_hand Le,marker_type) ; 

int vd i_h a nd l e ; 

short marker_typeC4U; 


Returns in the array marker_type the current 
colour, writing mode and height in that order). 

marker attributes (type. 

VQ.MOUSE 

GEM VDI 

vq_mouse ( vdi_hand Le, Sbutton, 8x, &y); 

int v d i _h a n d l e ; 
short button, x, y; 


Returns the state of the mouse buttons. 


VQT_ATTRIBUTES 

GEM VDI 


vqt_attributes(vdi_handle,text_type); 
int vdi_handle; 
short t e x t_t y p e C 1 0 3 ; 

Returns in the array text_type information on the current text attributes 
(font, colour, angle, horizontal alignment, vertical alignment, writing mode, 
character width, character height, cell width, cell height in that order). 


VQT EXTENT GEM VDI 


vqt_extent(vdi_handle, string, extent); 
int vd i_h a nd l e ; 
short e x t e n t C 8 ] ; 
char * s t r i n g ; 

Returns in the extent array (xO, yO, xl,yl, x2,y2, x3,y3) the co-ordinates of 
a box that would surround the text of the string passed as a parameter. 


VQT FONTINFO GEM VDI 


vqt_fontinfo(vdi_handLe, &first_char, &last_char, 
distances, Smaxwidth, effects); 
int vdi_handle; 

short first_char, Last_char, maxwidth; 
short distancesC5D, effectsC3D; 

Returns information on the current text font. 
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VQT.NAME 


GEM VDII 


v q t__n a m e ( v d i _h a n d l e , font_no, f ont_name ) ; 
int vdi_handle, font_no; 
char *font_name; 

Returns the name of the font whose index is passed as a parameter. 

VQT WIDTH GEM VDI 




vq t_w i d t h ( vd i_ha nd l e , character, & c e l l_w i d t h , 

8 l e f t_o f f s e t , 8 r i g h t_o f f s e t ) ; 

int vdi_handle, character; 

short cel l_w i d t h , Left_offset, r i g h t_o f f s e t ; 

Returns the ceLL_width, and l e f t_o f f s e t and r i g h t_of f s e t of the 
given character. 

V RBOX GEM VDI 



v__r b o x ( v d i _h a n d l e , arr_xy); 
int vd i_ha nd l e ; 
short arr_xy[4]; 

Draws a rectangle with rounded corners using the line attributes. arr_xy 
contains the two opposite corners of the rectangle. 

V RFBOX GEM VDI 


C 


v_r f box ( vdi_hand Le, arr_xy); 
int vdi_handle; 
short a r r__x y C 4 3 ; 

Draws a filled rectangle with rounded corners using the fill attributes. 
arr_xy contains the two opposite corners of the rectangle. 


V RMCUR 


GEM VDI 


v_rmcur (vdi_handle ) ; 
int vdi__handle; 

Removes the mouse cursor. 
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VRO_CPYFM 

GEM VDI 

tt include <gemlib.h> 

v r o_c py f m ( v d i_h a n d l e , operation, arr_coords, 
mf db_source, m f d b_d e s t i n a t i o n ) ; 
int vdi_handle, operator; 
short arr_coordsC8]; 

FDB *mf db_source, *m f d b_d e s t i n a t i o n ; 


Copies a block of memory from a source area (mf db_sou rce) to a destination 
area (m f d b_d estination) performing a raster operation on the block. 

VR.RECFL 

GEM VDI 

v r__r e c f l ( v d i_h a n d L e , arr_xy); 
int vdi_handle; 
short arr_xyC4D; 


Draws a filled rectangle without a border using the fill 
contains the two opposite comers of the rectangle. 

attributes. arr_xy 

VRT.CPYFM 

GEM VDI 


^include <gemlib.h> 

v r o_c p y f m ( v d i _h a n d l e , operator, arr_coords, 
mfdb_source, mf db_destinati on, colours); 
int vdi_handle, operator; 
short arr_coordsC8], coloursC2]; 

FDB *mf d b_s ou r c e , *mf db_dest i na t i on; 

Similar to the vro_cpyfm function except that the source area is considered 
to be monochrome and is given the colours in the array colours when 
copied. 


VR TRNFM 


GEM VDI 


vr_trnfm(vdi_hand le, mfdb_source, mfdb_dest); 
int vdi_handle; 

FDB *mfdb_source, *mfdb_dest; 

Copies a memory area (described by mfdb_source) in standard format to a 
destination area (described by mfdb_dest) in device dependent format. 


V RVOFF 


GEM VDI 


v_rvof f (vdi_handle); 
int vd i_h a n d l e ; 

Cancels the effect of v_rvon. 
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V RVON 


GEM VDI 


v_rvon(vd i_hand le ) ; 
int vdi_handle; 

After a call to this function, all text written with v_curtext will be written 
in inverse video (white on black). 

IVSC FORM GEM VDI 


vsc_form(vdi_handle, mouse_f orm); 

int vdi_handle; 

mouse_formC37]; 

Re-defines the mouse form. The elements of the array are as follows: 


0 

X co-ordinate of hot spot 

1 

Y co-ordinate of hot spot 

2 

always 1 

3 

mask colour (normally 0) 

4 

data colour (normally lj 

5 to 20 

mask 

21 to 37 

data 


VS CLIP GEM VDI 


vs_c l i p ( vd i_h a nd L e , clip, c L i p_a r r ) ; 

int vdi_handle, clip; 
short clip_arrC4D; 

Enables (clip = l) or disables (c l i p = 0) clipping within the VDI rectangle 
clip.arr (xO,yO,xl,yl). 


VS COLOR 


GEM VDI 


vs_color(vdi_handle, colour_no, rgb_values); 
int vdi_handle, colour_no; 
short r g b_v a l u e s C 3 1 ; 

Sets the palette for a colour co L our_no to be the red, green & blue values 
(between 0 and 1000) in the array rgb.values. 
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VS CURADDRESS GEM VDI 


v s_c u r a d d r e s s ( v d i _h a n d L e , row, column); 
int vdi_handle, row, column; 

Positions the text cursor at position given by row, column. 



v_enter_cur. 


VSF COLOR GEM VDI 


vsf_color(vdi_handle, colour_no); 
int vdi_handle, colour_no; 

Selects the colour used for filling areas. 


VSF INTERIOR GEM VDI 


vsf_i nteri or (vdi_hand le, fi ll_type); 
int vdi_handle, fill_type; 

Selects the type of fill depending on the value of fill_type: 


0 

hollow fill 

1 

fill with the colour given by vsf_interior 

2 

use a pattern defined by vsf_style 

3 

use a hatch defined by vsf_s ty l e 

4 

use a user defined fill area defined by vsf_updat 


VSF PERIMETER GEM VDI 


vsf_perimeter(vdi_handle, perimeter); 
int vdi_handle, perimeter; 

Indicates if GEM is to draw a perimeter round filled objects (if 
perimeter = l) or not (perimeter=0). 


VSF STYLE 


GEM VDI 


vsf_sty le (vdi_hand le, style); 
int vdi_handle, style; 

Selects a fill pattern style (1 to 24) or hatch (1 to 12). 
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VSF UDPAT 


GEM VDI 


vs f_ud p a t ( vd i_h a n d l e , image, planes); 
int vdi_handle, planes; 
short * i ma g e ; 

Sets up a user defined fill pattern. 

planes indicates the number of planes in the design (16 =1 plane, 32= 2 
planes, 64 = 4 planes). 

image contains the bit pattern for the new pattern and should contain the 
same number of words as the value of planes. 


V_S H O W_C 

GEM VDI 

v_s h o w_c ( vd i_h a n d l e , count); 
int vdi_handle, count; 


Makes the mouse appear if count is zero. 


VSL.COLOR 

GEM VDI 

vsf_color (vdi_handle, colour _no); 
int vdi_handle, colour_no; 


Select the colour that is used for drawing lines. 


VSL_END 

GEM VDI 


vsl_ends(vdi_handle, start_type, end_type); 
int vdi_handle, start_type, end_type; 

Sets the style used for the ends of lines: 0 = normal, 1 = arrow, 2= rounded. 


VSL.TYPE 

GEM VDI 

vsl_type(vdi_handle, line_type); 

int vdi_handle, line_type; 


Sets the line style (0 to 7) that is used in drawing lines. 


VSL.UDSTY 

GEM VDI 

vsl_udsty(vdi_handle, style); 
int vdi_handle, style; 


Defines the user defined line style. 
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VSL.WIDTH 

GEM VDI 

vs L_udsty (vdi_hand Le, width); 
int vdi_handle, width; 


Defines the line width to be width (between 1 and 39) . 


VSM.COLOR 

GEM VDI 

vsf_color(vdi_hand le, colour_no); 
int vdi_handle, colour_no; 


Selects the marker colour. 


VSM.TYPE 

GEM VDI 

vsm_type(vdi_handLe / type); 
int vdi_handle, type; 


Selects the type of marker to be used (1 to 6). 


VST.ALIGNMENT 

GEM VDI 

v s t_a l i g n m e n t ( v d i _h a n d t e , hori z_a l i gn, vert. 

&ret_horizontal, &ret_verti cal ); 
int vdi_handle, horiz_align, vert_align; 
sort ret_hori zonta l, ret_vertical; 

_align. 

Defines the horizontal alignment (in horiz_align from 0 to 2) and vertical 
alignment (in ve r t_a l i g n from 0 to 5) for text. 

The values returned in ret_horizontal and r e t_v erti ca L are the values 
set. 

VST.COLOR 

GEM VDI 

vsf_color(vdi_handLe, colour_no); 
int vdi_handle, colour_no; 


Selects the text colour. 
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VST EFFECTS 


GEM VDI 


vst_effects(vdi_handle, effect); 
int vdi_handle, effect; 

Selects the effects to apply to text using the bitmap effect: 


bit 

effect 

0 

bold 

1 

light (greyed) 

2 

italic 

3 

underlined 

4 

outlined 

5 

shadowed 


VST FONT GEM VDI 


vst_font(vdi_handLe, font_no); 
int vdi_handle, font_no; 

Selects which font to use (font_no). 


VST HEIGHT GEM VDI 


V s t_h e i g h t C vd i _h a n d l e , requested_hei gh t, 8 c h a r_h e i g h t , 

8 c h a r_w i d t h , 

Seel l_h eight, 8 c e L L_w i d t h ) ; 
int vdi_handle, requested_height; 

short char_height, char_width, cel l_h eight, cell_width; 

Attempts to set the height of characters to requested_height. 

This returns the size actually selected which is never bigger than that which 
was requested. 


VST LOAD.FONTS GEM VDI 


fonts = v s t_l o a d_f o n t s ( v d i_h a n d l e , reserved); 
int vdi_handle, reserved, fonts; 

Load the fonts indicated in ASSIGN. SYS. Requires GDOS for use. 
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VST.POINT 

GEM VDI 

height = v s t_p o i n t ( v d i _h a n d l e , points, Schar 
8 c h a r_w i d t h , 

8cell_height, 8 c e l l_w i d t h ) ; 
int vdi_handle, points, height; 
short char_height, char_width, cell_height. 

_h e i g h t , 
cel l_ width; 

Selects the height of a character using points (l/72th of an inch) as the units. 

VST.ROTATION 

GEM VDI 

vst_rotation(vdi_handle, angle); 

int vdi_handle, angle; 


Specifies the angle of rotation of text characters. Possible values are : 
O=normal, 900, 1800 and 2700. 

VST_UNLOAD_FONTS 

GEM VDI 

vst_unload_fonts(vdi__handle, reserved); 
int vdi_handle, reserved; 


Frees the space used by loaded fonts. 


VSWR.MODE 

GEM VDI 

mode_se lected = vswr_mode(vdi_handle, writing_mode); 
int vdi_handle, wri ti ng_mode, mode_se lected; 

Selects the writing mode (l=normal, 2=transparent, 
transparent). 

3=XOR, 4=inverse 

This function returns the value that has been selected. 


VSYNC 

GEMDOS 

VsyncC ); 


Waits until the vertical screen interrupt. 
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WIND CALC 


GEM AES 


ret= w i nd__c a L c ( i n t e r i o r , attributes, 
xl, yl, w 1 , hi, 

& x 2 , &y 2 , & w 2 , & h 2 ) ; 

int ret, interior, attributes, xl, yl, w 1 , hi; 
short x2, y2, w 2 , h 2 ; 

Calculates the size of a window needed, returned in (x2, y2, w2, h 2), to give a 
workspace size of (xl, yl, w 1 , hi) if interior = 0. Or the size of the work 
area given the border size if interior =1. 

This doesn’t apply to a particular window, but is useful for windows in 
general, 

attributes gives which ‘gadgets’ a window has (see Section 3.2.3). 


WIND CLOSE 


GEM AES 


ret= wind_close(window_no); 
int ret, window_no; 

Close the window (window.no) which has been opened with wind_open. 
The value returned is zero if an error occurs. 


WIND CREATE GEM AES 


window_no = wind_create(attributes, x, y, w, h); 
int win d o w_n o , attributes, x, y, w, h; 

Initialises a window without opening it. 

The attributes are the same as for open_wi ndow. 

x ,y,w,h are the co-ordinates of the window. 

The value returned is the window’s handle, or negative if the window cannot 
be created. 


WIND DELETE GEM AES 


ret= w i n d_d e L e t e ( w i n d o w_n o ) ; 
int ret, window_no; 

Deletes a window (wi ndow_no) after it has been closed. 
The value returned is zero if an error occurred. 
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WIND FIND 


GEM AES 


window_no = w i n d_fi n d ( x , y ) ; 
int window_no, x, y; 

Returns the handle of the window under co-ordinate position (x,y). The 
Desktop is window number 0. 


WIND GET 


GEM AES 


//include <gemlib.h> 

ret= wind_get(window_no, type_info, &x, &y, &w, &h); 

int ret, window_no, type_info; 
short x, y, w, h; 

Returns in the parameters (x, y, w, h) information about the window 
depending on the value of type_i nf o: 

w F _ w x Y w H co-ordinates "of" 5e w ork area ~~ 

~wTl c x Y w H window co-ordinates 

w F _ P x Y w h previous co-ordinates of the windo w 

w F _ F x Y w H maximum co-ordinates of the window 

w f_h s L i D E position of the horizontal slider (1 to 1000) in x 

W F_v S L I dje position of the vertical slider (1 t o 1 0 00) in x 

w f_t op handle of the top window in x 

w f_f I R S T x ywh co-ordinates of the first clip ping rect ang le 

wf_nextxywh co-ordinates of subsequent dipping rectangles 

w f_h s L I s i z size of the horizontal slider (1 to 1000) in x 

w F_v s L I S i z size of the ve rtical slider (1 to 1000) in x 


The value returned by this function is 0 if an error occurs. 


WIND OPEN 


GEM AES 


ret= w i n d_o p e n ( w i n do w_n o , x, y, w, h); 
int ret, window_no, x, y, w, h; 

Opens a window that has been created with wind.create. The co-ordinates 
should be the same as, or smaller than the co-ordinates given to 
w i n d_c r e a t e . 
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WIND SET 


GEM AES 


^include <gemlib.h> 

ret= wi nd_set ( wi ndow_no, type_info, x, y, w, h); 
int ret, window_no, type_info; 
int x, y, w , h; 


Sets, using the parameters (x, y, w, h), the attributes of the window 
wi ndow_no depending on the value of type_i nfo: 


U F_ki N D 

the window attributes 

W F_N A M E 

the window title (x top 16 bits, y bottom 16 bits) 

W F _ I N F 0 

the window information line (x top 16 bits, y 
bottom 16 bits) 

U F_ C X Y W H 

window co-ordinates 

W F_H S LI D E 

position of the horizontal slider (1 to 1 000) in x 

WF_V SLIDE 

position of the vertical slider (1 to 1000) in x 

W F_T 0 P 

handle of the top window in x 

W F_H S L I S I Z 

size of the horizontal slider (1 to 1000) in x 

W F_VSLI SI Z 

size of the vertical siider (1 to 1000) in x 




WIND UPDATE GEM AES 


//include <gem L i b . h> 
ret= wi nd_upda t e ( pa ram ) ; 
int ret, pa ram. 

Permit or ban certain of GEM’s automatic control of the system depending on 
the value of pa ram: 


BEG_UPD ATE 

The application is writing to the screen. GEM 
won’t let the user pull down menus or ‘play’ with j 
windows. 

E N D__U P D A T E 

Cancel the effect of beg_update. Menus may be j 
activated once more. 

B E G_M CTRL 

The application is about to take control of the 
mouse. 

E N D_M CTRL 

Return mouse control to GEM. 


The value returned by this function is 0 if an error occurs. 


WRITE 


UNIX 


num = write(nf, buffer, bytes); 
int num, nf, bytes; 
char ^buffer; 

Writes bytes to the file number n f that has been opened using open, 
buffer is the address from which the bytes are read from the file. 
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bytes is the number of bytes to write to the file. 

num is the number of bytes that were actually written to the file. Generally 
this will be the same as bytes. However num may be less than this if an error 
occurs (the disk is full for example). 

If the value returned by the function is - 1 or is less than bytes an error has 
occurred. In this case the variable errno will contain an indication of which 
error. 



open, read, errno. 


GEMDOS 


XBIOS 


ret= xbiosCno, argl, a r g 2 . . . ) ; 
i n t no; 

Long ret, argl ,arg2, . . . 

Execute an XBIOS function using TRAP #14. 
no is the function number. 

ret is the value returned by the XBIOS function. 

argl, arg2... are the parameters for the particular XBIOS function. 



bios, gemdos. 


XBTIMER 


GEMDOS 


no_it = Xb t i me r ( t i me r_no, controL_reg, data_reg, 
rout i ne_adr ); 

int no_it, timer_no, control_reg, data_reg; 
char *routine_adr; 

Initialises a 68901 timer. 

time r_n o (0-3) indicates which timer is to be initialised (A, B, C or D). 

control_reg and data_reg are the values (bytes) to write to the control 
and data registers of the timer. 

Finally the interrupt routine for each timer event is passed as the 
routine_adr parameter. 
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Exercise Answers 


Exercise 1 

mai n ( ) 

£ 

printf("he\nlto "); 
pri nt f ( "How are\nyou ?\n">; 
printfC" press a key\n" ); 
evn t_keybd ( ) ; 

> 

Exercise 3 

char chi, c h 2 ; 
mai n( ) 

chi = evnt_keybd ( ) ; 
ch2 = evnt_keybd ( ) ; 
putchar(chl); 
putchar(ch2); 
evn t_keybd ( ) ; 

> 

Notes : 

• The variables chi and ch2 could be declared as char, short or int - 
it does not matter. 

• More than one variable can be declared in the same statement by 
separating them with commas. 

Exercise 4 

int vl, v2, V 3; 
mai n ( ) 

■C 

printfC'Here are three values : %d, %d and %d\n", vl , v2, v3) ; 
evnt_keybd ( ) ; 

> 

There is nothing complicated here. The evnt_keybd() call just waits 
for a key to be pressed so you can admire the results of the program. 
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Exercise 5 


int num; 
ma i n ( ) 

num = Random (); 
i f ( num%2 == 1 ) 

-C 

printfC'The number %d is odd\n", n); 
num = num + 1; 

> 

else 

printfC'The number %d is even\n", n); 
evnt__keybd( ); 

> 

If the number num is odd, we write a message to this effect and add 
one to this number. 

If num is already even, we just need to write a message on the screen. 

Exercise 6 

int i ; 
ma i n( ) 

•C 

i = 20; 
while ( i ) 

printf("%d has square %d\n" , i, i * i ) ; 

i — ; 

> 

evnt_keybd ( ) ; 

> 

There’s a bizarre bit in this program, i--. This is actually very 
simple. These three characters subtract one from i . This is 
equivalent to the instruction: 

i = i - 1 ; 

But i — , takes less time to write and can execute quicker. 
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There’s a similar trick to add one to a variable. For example to add one 
to the variable sumwe can write 

sum = sum + 1; 

or equally well : 

sum++; 

There’s another trick in this program. A condition is either true or 
false. False is represented by zero. True is represented by any other 
value. Thus 0 is taken as false and any other value as true. 

In our example the condition in the statement while ( i ) is 
therefore true whilst the variable is not zero. The set of two 
instructions are thus executed until i is zero. When i becomes 0 the 
program stops. 

Exercise 7 

i n t i ; 
m a i n ( ) 
t 

for(i = 20; i>0 ; i--) 

printfC" /od squared is % d \ n " , i, i * i ) ; 
evnt_keybd(); 

> 

The variable i varies between 20 and 1 in the loop, 
i — is used to subtract 1 from the variable i . 

Exercise 8 

int i, sum; 
m a i n ( ) 

sum = 0 ; 

for (i = 1; i <= 100; i++) 

sum + = i ; 
evnt_keybd(); 

> 

The variable sum contains the sum of the hundred numbers. The 
variable i is the index that varies from one to a hundred. 

The instruction 

sum += i ; 

looks a bit funny. And in fact it is. This is equivalent to 


Exercise Answers 


HiSoft C 


Page 291 


sum = sum + i; 

The only difference is that it is to quicker to type and execute. 
The operators -= /= *= %= work in a similar way: 


sum 

- = 

i ; 

sum 


sum 

— 

i 

r 

sum 

/ = 

i ; 

sum 

= 

sum 

/ 

i 

r 

sum 

* = 

i ; 

sum 

= 

sum 

* 

i 

r 

sum 

ii 

i ; 

sum 

= 

sum 

% 

i 

r 


The statements on the left are equivalent to the statements on the 
right in the above table. 

The operator % is the remainder operator. 

The statement 

i ++; 

is used to add 1 to i as we have seen in Exercise 6. 

Exercise 9 


i n t c h ; 
ma i n ( ) 

for (ch = 32; ch < 256; ch++) 

putchar ( ch ) ; 
if (ch % 16 == 0) 

printf ("Xn"); 

> 

evnt_keybd ( ) ; 


This program displays the characters for the ASCII codes 32 to 255. 

The statement: 

putchar(ch); 

writes the character corresponding to the ASCII value in ch. 
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The conditional 

if (ch % 16 == 0) 

p r i n t f < " \ n " ) ; 

is to tidy the display. The program writes 16 characters per line. 
After 16 have been written, i.e. when i is divisible by 16, then the 
following characters are written on the next line. To do this HiSoft C 
executes the statement: 

p r i n t f ( " \ n " ) ; 

which puts the cursor on the start of the following line. 


Exercise 10 

Here’s the version of the program using a switch statement: 


char c; 
m a i n ( ) 
i 

d o 


> 

w h i L e 

> 


c = evnt_k e y bd ( ) ; 
switch (c) 
f 

case ' a ' : 
case * b ' : 
case ’ A ' : 
case ' B ' : 

putchar(c); 
break ; 
default : 

putcharC 1 * ' ) ; 

} 

( c ! = ' ’ ) ; 


The variable c is of type char; it’s used to store the character that is 
typed at the keyboard. 

We’ve used ado...while loop to repeat the reading of a character 
and the echoing on the screen. 
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The C language lets us manipulate constants that represent the 
ASCII code for characters. In fact these constants are of integer type. 
The syntax for these character constants is that they are enclosed in 
single quotes. So you can write, for example, 

c = 1 a ' ; 

This instruction stores the ASCII code for a in the variable c . 

These constants can be used anywhere an integer constant could be 
used, in particular in switch statements. The ASCII code for A is 65, 
so c a s e ' A ' is equivalent to c a s e 6 5. 

In our example, if the character typed on the keyboard is a, b, A or B, 
then it is echoed to the screen using the statement: 

putchar(c); 

Remember that putchar is a function to write a character on the 
screen. Its parameter is the ASCII code of the character to write. The 
default part lets us cope with all the other characters. If the key 
pressed is not a orb then a star is written on the screen. 

The looping condition is ( c ! = 1 * ) . This is to test if the space bar 

was pressed. ' 1 represents the space character; it is a single space 
between two apostrophes. 

The two characters ! = mean “is different to”. This is equivalent to <> 
in BASIC. Note that the test “is equal to” which is = in BASIC, is == in 
C. C distinguishes between the assignment operator which is written 
with a single equals sign and the equality operator which is two 
equals signs. 

The following program is equivalent to the previous one but it uses an 
i f statement instead of a s w i t c h . 

char c; 
ma i n ( ) 

do 

c = evn t_keybd ( ) ; 

if ( c == ' a ' || c== ' b 1 || c = = ’ A ' || c== ' B * ) 
putchar(c); 

else 

put cha r ( ); 

> 

while (c != ' ' ) ; 

> 
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You can see that the variable c is of type char. The program loops 
reading a character and then writing one to the screen. 

In place of the sui t c h statement we’ve got an i f statement. The 
condition is a bit odd. The expression c = = ' a ' tests if the variable c 
contains the ASCII code for the character a . We also test if c is equal 
to the codes for the characters b, A and B. Between these four tests 
there are a two vertical bars | | . They mean “or” and are equivalent to 
OR in BASIC. The i f condition in the program above is therefore: 

if ( c is equal to ’ a ' or c is equal to ' b ' or c is equal * A ’ or c is equal 
to 'B'). 

In this case we echo the character to the screen, otherwise (else) we 
display a star. 


Exercise 1 1 


ma i n C ) 


> 

n o n e ( ) 

> 


noneO; 


Another version: 


mai n( )(none( );>none( ){> 
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Exercise 12 


char c ; 
i n t value; 
m a i n ( ) 
i 

printfC" Type two numbers separated by a space, \n" ); 
printf ("then press Return\n " ); 

printf("Sum = %d\n", read_number ( ) + read_number() ); 

evnt_keybd( ); 

> 


r e a d_numb e r ( ) 

{ 

value = 0; 
c = getchar ( ); 
while (digit(c)) 

■C 

value = value*10 + c - ' 0 ' ; 
c = getcharC); 

> 

return (value); 

> 


digit(ch) 
char c h ; 
i 

if ( ch >= 'O' 
return 

else 

r e t u r n 


> 


&& ch <= *9') 
(1 ); 

( 0 ); 


The function digit has a parameter. It is a character. If it is a digit 
the function returns 1 (true). If not it returns 0 (false). 


The two characters && mean “and”. This is equivalent to BASIC's 
AND operator. The condition: 


c h > = 
is true if c h > = 
Thus digit(ch) 


•O' && ch <= ’ 9 ' 

' 0 ' and c h <= 1 9 ' are both true, 
is true if it is a digit, and false otherwise. 
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The r e a d_n umber function reads a positive number from the 
keyboard. The digits are read one by one as they are typed using the 
statement: 

c = getcharO; 

The variable value contains the value of this number. It is calculated 
as the individual digits that make up the number are read. 

The expression c - 'O' represents the value of the digit between 0 
and 9 when c contains the ASCII code of a digit between '0 ' and ' 9 ' . 

For example, suppose we have already typed the two digits 1 0 on the 
keyboard and then press 5 to make 10 5. The value variable will 
contain 10 and c will be ' 5 ' for this digit. c-'O' is 5, so 
value*10 + c-'0' is 105. 

Finally the variable va l u e is returned to the main program. 

The main function has three pri ntf function calls. The third one 
displays the value read_number() + read_number(). This is the 
sum of the two numbers that have been read from the keyboard. 
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Exercise 13 


The program below is well commented. The comments are enclosed 
with /* and */ character sequences. 


int winl, win2; 
m a i n C ) 

/* open window 1 */ 

winl = op e n_w i n do w ( 409 5 , 20, 20, 200, 150, 

" window 1 ", " press a key "); 

/* write to the window */ 

print _w indowCwinl, "hi !"); 

p r i n t_w i ndow C wi n 1 , "This is window 1"); 

evnt_keybdC); 

/* open a second window */ 

win 2 = open_wi ndow ( 40 9 5 , 200, 80, 200, 110, 

" window 2 ", " press a key "); 

/ * position the text in window 2 Line 4 column 2 * / 


p os_ w i n do w ( w i n 2 , 4 

/* write "hi !" in 
p r i n t_w i ndowCwi n2, 
evnt_keybdC); 

/* clear inside wi 
clear _w indowCwinl ) 
evnt__keybd(); 

/ * clear inside wi 
c l e a r_w i ndowCwi n2) 
evnt_keybd( ) ; 

/* write to window 
pri nt_wi ndowCwi n2, 
evnt_keybdC ); 

/* close window 2 
c l o s e_w i ndowCwi n2) 
/* clear inside wi 
c L e a r_w indowCwinl) 
/ * write in window 
print _ w indowCwinl, 
evnt_keybdC ); 

/ * close window 1 
c l o s e_w indowCwinl ) 


, 2 ); 


wi ndow 
"hi ! " 

2 

>; 

line 4 column 

ndow 1 

*/ 


r 



ndow 2 

*/ 





2 */ 
"This 

i s 

window 2"); 

*/ 



/ 

ndow 1 

*/ 



' 1 */ 

"This window 1 again"); 

*/ 


2 


*/ 


> 
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Exercise 14 


i nt wi ndow; 
int x, y, w, 
i nt i ; 
ma i n ( ) 

{ 


h; 


X = 

Ra 

ndom ( ) % 

100; 






y = 

Ra 

ndom ( ) % 

50 + 

20 

r 




w = 

Ra 

ndom ( ) % 

(600 

-x) 

+ 

5 

0; 


h = 

Ra 

nd om ( ) % 

(200 

-y) 

+ 

5 

0; 


wind 

ow 

= o p e n_ 

,w i ndo' 

w(4i 

095 

r 

x, y. 

w , h , 




" moi 

re 

r 

" 

press 

a key"); 

size 

w 

i n dow ( w i 

ndow. 

&x 

, 8y 

, 8w, 

& h ) ; 

for 

(i 

= y+h; 

i > y 

; i 

- = 


4) 




d raw C x + 

w, i , 

x. 

y+ h 

>; 


for 

(i 

= x + w; 

i > x 

; i 

- = 


6) 




d r aw ( i , 

y r x 

r y 

+ h ) 

; 



e vn t 

_k 

e y b d ( ) ; 








c l o s e_w i ndou(wi ndow) ; 
} 


The integers x,y,w and h represent the size of the window. They are 
defined with the help of the four calls to the Random function. 

Then the window is opened. All the gadgets are drawn because the 
the first parameter to open_wi ndow is 4095. 

The s i z e_w indou function stores the size of the usable area of the 
window in x,y,w,h. This is not the same as the original size of the 
whole window because of the presence of the sliders, title etc. 

The for loops draw the lines as rays from the bottom left comer at 
co-ordinates (x, y+h) 

The program then waits for a key to be pressed and closes the 
window. 
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Appendix B 
HiSoft C Language 
Reference 


HiSoft C for the ST corresponds to the language described in 
Kemighan & Ritchie in their book "The C language" (first edition). 


B.l Lexicographic elements 


A lexicographic element is the smallest unit in the language. They are 
the bricks that make up a program. 


B.1.1 The keywords 


The following words are the keywords of the C language. They must 
be typed in lower case. 


break 

case 

char 

conti n u e 

default 

d o 

double 

else 

extern 

float 

for 

goto 

i f 

i n t 

long 

r e g i s t e r 

return 

short 

si z e o f 

static 

struct 

s w i t c h 

t y p e d e f 

uni on 

unsigned 

void 

w h i l e 



These words can only be used as keywords. 

The names of library functions are also considered keywords. They 
must only be used for calling these functions. You may not re-define 
a library function identifier. 

When you type the name of a library function, only the first eight 
characters are required. HiSoft C can automatically add the 
remaining characters. For example, if you type vst_un lo HiSoft C 
automatically displays v s t_u n l oa d_f o n t s . 
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B.1.2 Identifiers 


A C identifier represents a variable. 

It is made up of a set of alphanumeric characters. Only the first eight 
characters are taken into account. 

The legal characters in an identifier are letters (upper or lower case), 
digits and the underline Identifiers may not start with a digit. 

Upper and lower case letters are considered different. Thus, i d e n t is 
not the same identifier as I D E N T . 


B.1.3 Integer constants 


Integer constants may be expressed in decimal, hexadecimal or octal. 

• A decimal constant is a sequence of digits which does not start 
with zero. 

• An octal constant starts with a zero and is followed by a set of 
digits between 0 and 7. An error message is given if 8 or 9 is used 
in an octal constant. 

• A hexadecimal constant starts with a 0, followed by an x or X 
and a sequence of hexadecimal digits. The hexadecimal digits 
are 0 to 9, a to f (or A to F) with the letters indicating the values 
1 0 to 15 respectively. 

A constant may be followed by a letter L or L which indicates that the 

constant is of type long. 

Note that a sign does not make up part of a constant but is 

considered a unary operator. 


B.1.4 Floating point constants 


A floating point (or real) constant is a collection of the following 
elements: 

a whole part, decimal point, fractional part, exponent. 

The decimal point and fractional part or the exponent may be 
omitted, but not both. 

All floating point numbers are considered double precision. 
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B.1.5 Character constants 


A character constant consists of a character enclosed in two 
apostrophes: ' A ' . 

There are ways of writing certain special characters: 


— n , 

new line 

' \b ’ 

backspace 

•At* 

tab character 

• \ r ' 

carriage return (no linefeed) 


apostrophe 

» \0 1 

null character 


You can also create character constants by specifying their ASCII 
code in base 8,10 or" 16: ' \23' (character with ASCII code 23 
decimal), ' \ 0 1 2 ' (character with ASCII code 12 octal) or ' \x4 5 ' 
(character with ASCII code 45 hex). 

The value of a character constant is an unsigned integer equal to the 
ASCII code for the character. 


B.1.6 String constants 


A string constant consists of a set of characters enclosed in double 
quotes and may include all the possible special characters (\n, OxC 
etc, as described above. 

A double quote may be included in a string constant by using \ " . 
Strings may be of any length, even 0 characters. 

HiSoft C inserts a null character (code 0) at the end of every string to 
mark its end. 

The value of a string is a pointer to the first byte of that string. Thus, 
when the interpreter encounters the string "qwerty" it returns the 
address where the string is stored in memory not the string itself. 
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B.1.7 Operators 

An operator consists of one, two or three characters. 

Single character operators: 

+ -*/% A &~ | = <>? ; ! ()[:, 

Multi character operators 

++ — << » -> <= >= == ! = && || 

-= += * = /= %= g= *= | = « = >>= 

These operators consisting of several characters may not have their 
components separated by white space. 

B.1.8 Comments 

Comments start with / * and finish with * / . 

Comments may not be nested. 

They must be opened and closed on a single line. The HiSoft C editor 
will not let you enter comments that are not closed. 

When loading a file containing comments that are several lines long, 
HiSoft C automatically inserts the / * and * / symbols at the start 
and end of each line. 


B.1.9 Separators 


The separators split up the lexicographic elements. These are spaces, 
tab characters and end of line characters. 

The ; (semi-colon) character terminates statements. 

The curly brackets -C and > characters are used at the start and end 
of blocks of statements. 
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- 

V 

V. 


Vw 




B.2 The Pre-processor 

B.2.1 Define 

The //define directive has several differences to that given in K & R 
because HiSoft C is interpreted rather than compiled. 

The syntax is as follows: 

//define name constant 

//define nameCargl, a r g 2 , . . . ) expression 
(without a semi-colon at the end). 

The value given in //define must be used in expressions. A macro 
may not be used outside of expressions. 

Thus it is impossible to re-define a type in this way: 

//define int WORD 

You must use t y p e d e f instead. 

It is also illegal to define a variable with the same name as a macro. 

Nested defines are also illegal. That is a define may not reference a 
value that is given by another define. 

You can also write: 

//define PI 3.141592 
//define hello "hello" 

to define both floating point and string constants. 

Examples : 

//define SIZE 512 

//define UPPER(a) ((a) >= 'A' && (a) <= 'Z') 


V- 
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B.2.2 Include 

The ft include directive loads a header file. The syntax is 
//include " f i L e_name " 

//include <f i Le_name> 

The version with double quotes looks for the file in the current 
directory. The version with greater than and less than signs looks in 
the \ header directory on the current drive. 

Include files may themselves include other files. 


B.2.3 Conditional Interpretation 


It is possible to either interpret, or not interpret depending on a 
condition. This is performed with the help of the #if, U i f d e f and 
*/ i f n d e f directives. 


//if expression 

is true if the expression is non-zero (and if the identifiers in the 
expression are properly defined). 

//ifdef identifier 

is true if the identifier is defined. 

//ifndef identifier 


is true if the identifier is not defined. 

If one of these three directives is used there must be a following 
//end i f . 




So, if the condition is true the lines between the U if and the tt e n d i f 
are interpreted. If the condition is false these lines are ignored. 


The //else directive may be used. This causes lines between an i f 
directive and the ft else to be interpreted if the condition is true and 
the lines between the #else and the //end i f to be interpreted if the 
condition is false. 
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Example: 


U if LABEL 

/* Lines interpreted if LABEL is non-zero */ 

#e Lse 

/* Lines executed if LABEL is zero */ 

#endi f 

The identifier I C is always defined as 1 so that code may be added 
that will only be used under the HiSoft C interpreter. 


B.3 Operators 


The C language operators are summarised below together with their 
priority: 


15 

( ) 

function call 

15 

11 

array index 

15 

. 

direct selection of a structure element 

15 

-> 

indirect selection of a structure element 

14 

* 

indirection 

14 

& 

address calculation 

14 

- 

unary minus 

14 

1 

unary logical negation 

14 

~ 

bitwise negation 

14 

+ + 

increment 

14 


decrement 

13 

* 

multiplication 

13 

/ 

division 

13 

% 

modulus 

12 

+ 

addition 

12 

- 

subtraction 

11 

< < 

shift left 

1 1 

> > 

shift right 

10 

< 

less than comparison 

10 

> 

greater than comparison 

10 

< = 

less than or equals comparison 

10 

> = 

greater than or equal comparison 

9 

= = 

equality comparison 

9 

| - 

inequality 

8 

& 

bitwise AND 

7 

A 

bitwise exclusive OR 

6 

1 

bitwise OR 

5 

&& 

logical AND 
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nr 

1 1 

logical OR 

3 

? : 

conditional operator 

2 

= 

simple assignment 

2 

+ = 

/ = 
<< = 
i = 

- = *= operation & assignment 

%= >> = 

&= A = 

1 

r 

sequential evaluation [ 


Operator priorities may be changed by using parentheses. 


B.4 Variable types 


HiSoft C recognises all the types defined in K&R. 


B.4.1 Simple types 


voi d 


the type of a function that doesn't 
return anything. This type may only 
be used with functions and may not 
be used with structured types 

char 


8 bit unsigned integer 

short 


16 bit signed integer 

unsigned 

short 

16 bit unsigned integer 

i nt 


32 bit singed integer 

unsi gned 

i nt 

32 bit unsigned integer 

Long 


32 bit signed integer 

unsi gned 

long 

32 bit unsigned integer 

float 


64 bit double precision floating point 
in IEEE format 

double 


64 bit double precision floating point 
in IEEE format 
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B.4.2 Structured types 1 

As well as the simple types described above, types may be 
constructed from other types: 

• Arrays of any type 

• Pointers to any type 

• Functions returning a particular type 

• Structures consisting of simple types, arrays, pointers, unions 
or other structures. 





Unions containing simple types, arrays, pointers, structures or 
other unions. 


The rules for building structured types can be used recursively, so 
that an array may contain arrays and a pointer may point to an 
array of structures which contains pointers etc. 

Be careful; in HiSoft C the maximum number of array dimensions is 
16 and for the same reason the maximum depth of pointer 
indirections is 16 . 



B.5 Declarations 

A variable declaration is constructed as follows: 


memo ry__c L a ss type decl_item1, d e c l_i t e m 2 , . . - ; 


B.5.1 Memory classes 


Memory classes indicate where the declared variable is to be 
physically stored. It may be stored in ordinary memory, on the 
stack, in a register or even in another module. 

w The class also indicates the scope of the variable, that is to say, the 
area of the program where the variable may be accessed. 

V 
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The memory class may be omitted. In this case if the variable is 
declared outside a function the variable is considered global to the 
module. If the variable is declared within a function it is considered 
local to that function. No more than 40 local variables, including the 
parameters may be declared within a function. This would be very 
poor style, you should split the function into several smaller ones. 

The available memory classes are as follows: 


extern 

indicates that a variable is declared in another 
module. 

s t a t i c 

indicates that the scope of the variable is 
strictly limited to the module/function in 
which it is declared. 

register 

used inside a function definition indicates 
that the variable is to be stored in a register 
rather than on the stack. 

typedef 

indicates that the “variable” declared is to be 
considered a new type of variable. This new 
type is equivalent to the type specified in the 
typedef. 


B.5.2 The type 


The type part of a declaration consists of one of the types described 
above or a name defined using typedef. 

The typedef is optional when declaring functions. In this case the 
function is taken as of type i n t . 


B.5.3 Declared items 


The following element in a declaration is a list of declared items, 
separated by commas if there are several. 

A declared item consists of an identifier (the name of the variable) 
together with characters indicating if it is a pointer, a function, a 
structure or an array, separated by commas if there are several. 

A declared item may contain an initialiser preceded by an = sign. 
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B.5.4 Initialisers 


For variables which are declared outside functions (global variables), 
simple, pointer and array types may be initialised. However 
structure types may not be initialised. 

For variables declared inside functions, only simple and pointer 
types may be initialised. Thus it is impossible to initialise arrays or 
structures within functions. 


B.6 Statements 


HiSoft C supports all the statements described in K&R. 

• if else 

• while 

• do while 

• for 

• switch case default 

• break 

• continue 

• return 

• goto 

A break instruction in a switch statement may only be used at the 
end of a list of statements. Thus you may not use: 


if ( a ) 
l 

a — ; 
break; 

> 


a + + ; 
break; 
default: 

/ * etc... * / 

The program section above should be replaced by 


case 1 1 ' : 

if ( a ) 

else 

break; 

default: 

/* etc 


a — ; 
a + + ; 

*/ 
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The goto statement must reference a label in the same C block as the 
goto statement itself. It is impossible to goto another block. 

A C block is a sequence of statements enclosed in curly brackets. 

The following two programs are not accepted by HiSoft C: 


i 


here: 


and 


> 

> 

here: 

f 

> 


goto here; 


goto here; 


On the other hand, the following is allowed: 


here: 

> 

if ( cond ) 

goto here; 

> 






B.7 Operations on types 






B.7. 1 Pointer conversions 


A pointer to a type may not be assigned to another pointer if it is not ^ 
of equivalent type (the same level of indirection) without an explicit 
type conversion. 


S- 
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So, storing an integer in a pointer variable gives an error message 
unless you use a cast. 


V 

L 






•c 

char * p ; 
i n t i ; 

p = i; /* illegal */ 

p = (char*)i; /* allowed */ 

> 

Be careful when assigning a pointer to an integer. Except with 
pointers to characters, pointers must have even addresses; using 
odd addresses will give an error message. 


B.7.2 Arrays and pointers 1 

Arrays and pointers are strictly equivalent. In practice, the 
statement tabCindex: is converted to*(tab+index). 

When adding an integer to a pointer the value of the integer is first 
multiplied by the size of the object that the pointer points to. 

So, if p is a pointer to i n t , p+ 1 adds 4 to p (4 * the size of an i n t). 





V 


B.7.3 Functions 


As far as HiSoft C is concerned there are two classes of functions: 

• HiSoft C library functions and loaded compiled (or assembled) 
functions. These are stored in machine language and are executed 
directly by the 68000. 

• User functions written with the Interpreter's editor. These 
functions are stored in source form and are not executed directly by 
the 68000 but are interpreted by HiSoft C. 

These two classes of functions are distinct; the 68000 cannot execute 
an interpreted C routine and HiSoft C cannot interpret a library 
function. This differs from a compiled C program where all functions 
are in 68000 code. 

With an interpreted C function there are two ways of calling it. You 
can call it directly or find its address and store this as a pointer to a 
function. This provides a method of passing functions as parameters 
to other functions. 
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With a compiled C function (library function or a compiled one that 
has be loaded) you can only call it; it is not possible to find its 
address, this will give an error message. 

Thus HiSoft C pointers to functions can only point to interpreted 
functions not compiled ones. 


B.7.4 Structures and unions 


The possible operations on pointers are accessing one of its 
members, (via or or calculating its address. All other 

operations, such as assignment or passing as a parameter, are 
illegal. 

When you access a structure member (using or the 

identifier on the left hand side must be a structure (with " . ") or a 
pointer to a structure (with and the identifier on the right 

must be a member of a structure or union. 
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AppendixC 
Error Messages 

Here is a detailed commented listing of HiSoft C's error messages. 


C.l Interpreter Error Messages 

When an error is found whilst running a program, a window opens 
with a description of the error that has occurred. Finally the cursor 
is positioned at the precise place that the error was found. However 
sometimes the actual cause of the error may be elsewhere (e.g. 
omitting a declaration). 

0 Program execution stopped 

The program has been interrupted. The user has pressed two of the 
Control, Shift or Alt keys. Alternatively a stop, exit or abort 
statement has been encountered. 

J Syntax error 

HiSoft C does distinguish between some little syntax mistakes. This 
error doesn’t appear as frequently as with some BASICs! 




2 Missing ; 

A semi-colon was expected at the end of a declaration or statement. 








3 Missing parenthesis 

A parenthesis has been opened but not closed or vice versa. 

4 Out of memory 

You've run out of memory. Well done! Seriously though, try removing 
Desk accessories, ramdisks or other memory resident programs. 
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5 


Missing integer 


HiSoft C was expecting to find an Integer, perhaps, as an array index. 
Empty array indices are only allowed in function parameter 
declarations. 

6 Too many dimensions 

The maximum number of dimensions in an array and the maximum 
number of indirections off a pointer is 16. 

7 Duplicate declaration 

A global variable has been declared twice. This is strictly illegal. 
Neither may you have two structure field identifiers with the same 
name. 

8 Undefined structure name 


A reference has been made to a structure that has not been defined. 
Please define it. 

9 Missing structure name 

HiSoft C has expected to find the name of a structure but it has found 
something else. 

10 Empty structure 

Either there are no elements declared in the structure or the 
structure name is used with indirection. 

1 1 Missing identifier 

HiSoft C expected to find a variable identifier. This error can occur if 
you omit the parameters in a function definition. 

12 Duplicate declaration of local variable 

A local variable is declared twice within the same function. 
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... 


13 Bad type for a function argument 

Function arguments may not be of type function, union or structure. 

If you need to pass a union or function as a parameter, pass pointers 
to them. 





14 Name mismatch in the parameter list 

The function argument list and the declarations of those arguments 
disagree. 






15 Too many local variables 

The maximum number of local variables in a function (together with 
parameters) is 40. This error is probably due to very bad 
programming style; split your function up. 

17 Parameter not declared 


A parameter is present in the argument list but there is no 
declaration for it. 


18 Missing } 

A block has been opened using { but not closed with >. Use the Home 
key (see the Cursor key item on the Help menu). 

19 Undefined label 


There is a reference to a variable that has not been declared. Perhaps 
it has been mistyped. 




c 


20 Illegal function dec l aration 

There is an error in the declaration section of a function, or the entire 
body (the statements) has been omitted. 

21 Variable t yp e error 

The type specified is illegal. For example there is no such thing as an 
unsigned struct. 
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22 


No reference to local label 


A local variable has been declared but is not used. 

23 Missing main function 

The function main has been left out. Every program must have a 
function main so that execution can start. 

24 Keyword found in an expression 

A language keyword has been found in an expression. 

25 'lvalue" required 

An “lvalue” is a value that you can assign to, i.e. can appear on the left 
of an = sign. You can have a = 1 ; because a is an lvalue. But 1 -5 is 
illegal because 1 is not an lvalue. 

So this error occurs when the left hand side of an assignment 
statement is illegal. 

It will also happen when using & the “address or operator. The 
argument to this must be an lvalue. Note that the name of an array is 
not an lvalue. 

26 Pointer assigned to an integer 

HiSoft C forbids assigning pointers to integers without using a cast. 

27 Integer assigned to a pointer 

HiSoft C forbids assigning integers to pointers without using a cast. 

28 Pointer type mismatch, operator '=' 

You cannot assign a pointer value to another one, unless they point 
to the same type, without using a cast. 

29 Illegal operator for pointer arguments 

For example, pointers can not be multiplied together. 
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30 Division by zero 

An attempt to divide by 0 has been made. Often this will be caused by 
a variable that has been assigned an inappropriate value. 

31 Integer used with operator 

The indirection operator * must be followed by a pointer or array. 

32 Pointer used instead of an integer 

A pointer, rather than an integer has been used to index an array. 

33 Incorrect pointer value 

The interpreter has spotted the use of an un-initialised pointer, and 
rather than crashing the machine gives you this error message. 

34 DO without WHILE 

Ado statement has been found, but there is no corresponding 
while. Perhaps some curly brackets have been added or left out. 

35 ELSE without IF 

An ELSE statement has been found, but there is no corresponding 
while. Perhaps some curly brackets have been added or left out. 

36 CASE without SWITCH 

A CASE statement has been found, but there is no corresponding 
SWITCH. Perhaps some curly brackets have been added or left out. 

37 DEFAULT without SWITCH 

A DEFAULT statement has been found, but there is no corresponding 
SWITCH. Perhaps some curly brackets have been added or left out. 

38 Missing : in a CASE instruction 

The correct syntax of a CASE statement is: 
case [expression] : 

However the colon has not been found. 
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39 


Missing CASE in a SWITCH instruction 

Immediately after a SWITCH statement there must be either a C A S E 
(or default) statement, but there is something else instead. 

40 Missing { in a SWITCH instruction 

Immediately after a switch statement there should be a curly 
bracket. For example: 

switch (a) 

case 1: / * etc * / 

41 Missing parameters in function call 

A HiSoft C library call has been made and there aren’t enough 
parameters. Alternatively you may have got the function name 
wrong. The Help command can be used to check the number of 
parameters. 

42 Missing , in a function call 

Each parameter should be separated by a comma. A character that is 
neither a , nor a ) has been found after a parameter. 

43 Unknown operator 

Error in an operator. Or perhaps you have used a unary operator as 
a binary one or vice versa, e.g. + + , ! and ~ can only be unary 

operators. Thus i + + is legal but i ++ j is not. 

44 Too many parameters in a function call 

A HiSoft C library call has been made and there are too many 
parameters. Alternatively you may have got the function name 
wrong. The Help command can be used to check the number of 
parameters. 

45 Floating point value used with SWITCH 

Only integer or pointer values can be used in SWITCH statements, not 
floating point ones. 
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46 


Bad type for a function name 


v_ 



An attempt to pass an entire structure to a function has been made. 
Only pointers to structures may be passed. 

47 Bad function pointer usage 

An attempt has been made to use a pointer to a function as a 
function. For example, 

char (*fctC5D)<) /* declare an array of pointers */ 

fct(); /* call function */ 

To access an element in the f c t array the following should be used: 

fctC3D<) /* call function */ 







48 Stack full 

There have been too many recursive function calls and the stack has 
overflowed. This is almost certainly because of a programming error. 
For example, 

functionO 

i = 5; 

if (i > 2) 

functionO; 

> 

49 Bad usage for BREAK or CONTINUE 

break and CONTINUE statements may be used inside while, DO or 
for loops to change the order of execution, break statements may 
also be used in SWITCH statements. All other uses of these 
statements are illegal. 


i'S 



50 Bad value for shift number 

The second argument of << and >> (the shift operators) must not be 
negative. 

51 Integer value required with this operato r 

The logical operators ( A , ", | , 8) and modulo (%) can only be used with 
integers, not floating point numbers. 
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52 Floating point parameter expected 

A library function needing a floating point number has been passed 
an integer instead. 

53 Structure identifier expected 

Only structure variables may be used before the " . " and " - > " 
operators. 

54 Structure item expected 


A field structure name must be used after the " . " and " - > " 
operators. 

55 You can t use this operator on structure type 

Using " . " on a pointer to a structure or using on a structure 

variable. 

56 Forbidden usage made on structure type 

This operator may not be used on a structure variable. & to find the 
address may be used and members may be accessed using " - Apart 
from this all others are forbidden. 

57 Forbidden character 


An illegal character not recognised by the language, has been found 
outside a string or comment, for example a control character or 
character greater than 127. 

58 Missing (' after a library function name 

This message is also given if you try to calculate the address of a 
library function. 

59 Missing variable type 

The name of the type of a variable is expected after s i z e o f . 

60 Incorrect variable type 

An array type can not be used with s i z e o f or casts. 
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61 Preprocessor keyword expected 







c 

c 


A preprocessor keyword is expected after a // sign. 

62 Missing after '?' 

The only valid character after ? is the : of the ? : conditional 
operator. 

63 Bad function return value 

The value ina return statement is not the same as in its declaration. 

6 4 Too many items in an initialization 

Too many items have been used in an initialiser (normally an array) 
to match the declaration. 

65 Macro name expected after #define 

A non-empty macro name is required after a //define. 

66 Empty macro definition 

The entire body of a macro may not be empty. 

67 Forbidden operator in an initialization 

Only constants may be used in initialisers. For example, you can’t 
call a function inside a macro. 

68 You cannot initialize aggregates 

struct type variables may not be initialised. 

69 File name expected after #include 

An invalid file name has been used after //include. 


I N 



70 Too many include files 

No more than 8 include files may be loaded at the same time. 
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71 


You must check the "link at runtime" option to 
use #include 


To use the ft i n c l u d e facility you must first select the Link at runtime 
option on the Run menu. 

72 Cannot load include file 


The include file can not be loaded. It needs to be in the \ HEADER 
directory on the drive that HiSoft C was loaded from if < and > have 
been used and in the current directory if quotes are used. 

73 Bad type usage 

Error in a type when using s i z e o f or a cast. 

74 Bus error 


68000 exception. An attempt to access an illegal address has been 
made, such as one of the ST’s low memory variables. 

75 Odd Address access 

68000 exception. An attempt to indirect using an odd address has 
been made. 

76 Unknown instruction 

68000 exception. An illegal 68000 instruction has been encountered. 

77 Division by 0 

68000 exception. An attempt to divide by 0 has been made. 

78 CHK instruction 

68000 exception. An exception has been generated by a CHK 
instruction. 

79 TRAPV instruction 

68000 exception. An exception has been caused by a TRAPV 
instruction. 
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Supervisor mode required 



c 

c 


68000 exception. An instruction that can only be used in supervisor 
mode has been encountered. 

81 Trace mode 


68000 exception. An exception has been generated because we are in 
trace mode. 





82. Cannot initialize a local complex type variable 

Arrays and structures that are local to a function may not be 
initialised. See Appendix B. 

83 Goto out of local block 


goto's may not reference a label that is not in the same C block 
({...>) as the goto. See Appendix B. 






84 Label name expected after goto 

An item which is not an identifier has been found after a goto or the 
identifier used is declared as a variable. 

85 #endif or #else without #if 

Aflendif orflelse directive has been found without an associated 
//if, flifdef orZ/ifndef. 

86 #endif expected after #if 

A U i f directive has been used, but the end of the text has been found 
without encountering a U e n d i f . 


87 This label is already used in the function library 

w An attempt to re- define a variable which is already used in a library 
function has been made. 

c 
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C.2 Editor Error Messages 

101 Cursor is inside the block. Can't copy the block 

You may not copy a block to a position inside that block. 

102 The line is too long. Maximum length is 127 chars ^ 

The length of lines is limited to 127 characters. 

103 This line number does not exist 

You have entered a non-existent line number (there aren't that many 
lines in the file). x — ' 


104 No more windows! 


All the GEM windows have been used up. Close desk accessories or 
return to the Desktop. 




105 You ran out of memory... 


You’ve used all the available space. 


106 The file you want to load does not exist 


If this error occurs after the use of ^include make sure that the 
disk containing the HEADER folder is present in the drive from which 
HiSoft C was loaded. 

107 Search failed: String not found 




1 08 Disk error or disk full 


Either the disk is full or the disk can’t be read or written to, perhaps 
because there is no disk in the drive. v_ 


109 Comment is not closed on current line 

A comment must only be one line long. Add a * / at the end of the line. 
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1 1 0 Error in char or int constant on current line 


HiSoft C has found the start of a constant (octal beginning with 0, 
hex beginning with Ox ora character beginning with ' ) but it is 
incorrectly formed. 

1 1 1 Can't find end of string on current line 

A string of characters must be closed on the same line as it is opened. 
Perhaps there is a " missing. 

112 Syntax error in macro command 

The contents of a macro command, given by Shift and a function 
key is wrong. 

113 I can't give you help about this keyword 

There is no help file corresponding to this keyword. 

114 Error in project file line XXX 

The contents of the project file that you are tiying to load has an 
error on the given line. 


C.3 Loading Error Messages 

The following errors may be given when HiSoft C is loading: 

I can't load the resource file 

Make sure that you have all the F 1 . C to F 9 . C files present on the 
current disk. 

i can't run in low resolution 

Switch to Medium resolution using the Desktop. 

Too much memory left to the system 

So there’s not enough for HiSoft C to run. Use the System memory 
size command on the Run menu. 
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Appendix D 
Porting programs 


D. 1 Porting from the interpreter to 
a compiler 

Compiling a program written in HiSoft C doesn’t pose too much of a 
problem if you have a compiler. 

HiSoft C is almost totally compatible with Lattice C interpreted 
programs can be compiled almost immediately with Lattice C 5: see 
the Lattice C 5 manual for details. 

With other compilers, you may have problems because of the size of 
integers. Aztec C, for example, has a flag to enable 4 byte integers and 
you should use this. 

Moving to a new implementation of C can be tricky, you need to know 
the compiler, include files and libraries well. It is not something 
recommended for beginners. One problem to watch out for is that 
HiSoft C expects integers to be 32 bit: so you should use the 
appropriate compiler flags to ensure that this is the default. 

The general procedure to use is as follows: 

• Convert the program to ASCII format. HiSoft C interpreted 
programs are tokenised in a special way. To convert a program to 
ASCII load HiSoft C and choose Editor mode from the File menu (see 
Section 1.8). Then load the file and it will automatically be converted 
to ASCII and you can save it as ASCII. 

• For some HiSoft C specific functions (the GEM toolbox), the source 
is supplied in the SOURCE directory on Disk 2 for you to compile. 

If you have used the toolbox functions you will need to compile these 
files (compil.c, libwind.c, libdial.c, libmenu.c and 
libresou.c) and link with the object files produced. There’s an 
example of a linker file in c . L n k . 

de f i ne . h contains some constants that are built into HiSoft C. 
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If you are using Lattice C 5 you need not re-compile the Toolbox: you 
can use the library that is supplied with Lattice. 

Whichever compiler you are using, you must also rename your main 
function to be i c_ma i n. This is because the toolbox has to perform 
some initialisation. 


D.2 Porting from compilers to 
HiSoft C 


Porting programs in the other direction, written for a compiler to the 
Interpreter can be more difficult. 

First of all because programs run more slowly under the interpreter 
than when compiled. 

Also some compilers have extensions to the K&R standard (for 
example some of the features of the new ANSI C), 

The other possible main sources of incompatibilities are the fact that 
HiSoft C variables may not have the same name as a library function 
and the restrictions on the use of //define. See Appendix B for 
details. Remember that HiSoft C uses long (32-bit) integers as 
standard, so be especially careful if porting code that assumes that 
16 bit integers are being used. See Appendix B for details. 
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Appendix E 
Bibliography 


This bibliography contains our suggestions for further reading on 
the subject of C, the ST, and GEM. The views expressed are our own 
and as with all reference books there is no substitute for looking at 
the books in a good bookshop before making a decision. 

Please also note that none of these books on C describe HiSoft C for 
the ST in particular. Should an example program fail to work as 
expected please study the appropriate sections in this manual. 
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Books about C 


The C programming Language by Kernighan & Ritchie, 
published by Prentice-Hall 

The C programmer's bible, which is very expensive, unfortunately. 
There are two editions; the first one is more applicable to HiSoft C 
(and most compilers). The second edition covers the new ANSI 
standard which isn't implemented by many compilers (at least not 
until recently). If you have a lot of experience in, say Pascal, this is 
also a good tutoriail book. 

Learning to program in C by Thomas Plum, published 
byPrentice-Hall 

A tutorial book which starts from first principles. 

The Big Red Book of C by Sullivan, published by Sigma 
Press 


A cheap tutorial book. 

The C programming Tutor by Wortman & Sidebottom, 
published by Prentice Hall 

A cheaper tutorial from the publishers of K&R. 
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C at a glance by Adam Denning, published by 
Chapman & Hall 

Another low cost tutorial book that mentions the ‘other’ HiSoft C for 
Z80 computers. 


ST Technical Manuals I 


GEM Programmer's Guide Volumes 1 & 2 - VDI and AES 
by Digital Research 

— - 

The definitive guide to the VDI and AES, but marred by mistakes. 

Only available to registered developers. 

GEMDOS Specification by Digital Research 

The definition of the GEMDOS calls. Only available to registered 
developers. 


A Hitchhikers Guide to the BIOS by Atari Corp 

The definition of the BIOS and XBIOS calls, and corrections to the 
GEMDOS manual. This is accurate, a good read and updated 
regularly. Normally only available to developers. w 

The Anatomy of the Atari ST by Data Becker/Abacus 

L 

This book is the best documentation available for the user who is not 
a registered developer. It describes the hardware and non- GEM 
aspects of the operating system, including an (out-of-date) BIOS 
listing. Thoroughly recommended, despite its inaccuracies. 


GEM on the Atari ST by Data Becker/Abacus 

This describes programming under GEM, though is not as complete 
as the DR manual, but has similar errors. It describes calls mainly 
from C, although there is more reference to the 68000 than in the DR — 
manual. Better than no book at all on GEM. 
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Concise Atari 68000 Programmer's Reference 
by Katherine Peel, published by Glentop 


An alternative to The Anatomy of the Atari ST. It contains information 
on the ST's hardware, the operating system and GEM. Its coverage of 
the various levels of the machine is comprehensive, though a couple 
of sections are very inaccurate and some features are described that 
simply don't exist. It is rather difficult to find one’s way around as 
the layout is based on large numbers of tables and it lacks an index. 

Tricks and Tips on the Atari ST by Data Becker/Abacus 

This contains a wide variety of material, including an accurate 
description of the more esoteric ST BASIC commands, and good 
sample listings including a RAM-disk driver and desk accessory. 
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Appendix F 
Technical Support 


So that we can maintain the quality of our technical support service 
we are de tailin g how to take best advantage of it. These guidelines will 
make it easier for us to help you, fix bugs as they get reported and 
save other users from having the same problem. Technical support is 
available in four ways: 

Phone our technical support hour is normally between 3pm and 
4pm, though non-European customers’ calls will be 
accepted at other times. 

Post if sending a disk, please put your name & address on it. 

BIX™ our username is (not surprisingly) hisoft. Would UK 
customers please use CIX or more old fashioned methods; 
it’s cheaper for everyone. 

CEX™ our username is (still not surprisingly) hisoft. 

For bug reports, please always quote the program, computer and the 
version number of the program (the one displayed by the About box) 
and the serial number found on your master disk. 

If you think you have found a bug, tiy and create a small program 
that reproduces the problem. It is always easier for us to answer your 
questions if you send us a letter and, if the problem is with a 
particular source file, enclose a copy on disk (which we will return). 

Upgrades 


As with all our products, HiSoft C is undergoing continual 
development and, periodically, new versions become available. We 
make a small charge for upgrades, though if extensive additional 
documentation is supplied the charge may be higher. All users who 
return their registration cards will be notified of major upgrades. 

Suggestions ~ 


We welcome any comments or suggestions about our programs and, 
to ensure we remember them, they should be made in writing. 
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